Input and output HTML for OneNote pages

Learn about the input HTML you can use to create a OneNote page and the output HTML that's returned when you retrieve page content.

Last modified: January 22, 2016

Applies to: OneNote service

Note
See this topic on our new documentation site for consumer and enterprise OneNote APIs.

When you create a OneNote page, you send a POST request to the pages endpoint:

POST ../api/v1.0/me/notes/pages[?sectionName={section-name}]

POST ../api/v1.0/me/notes/sections/{section-id}/pages

The input HTML that you send in the request body represents the page content and structure. The OneNote API preserves the semantic content and basic structure, but converts the input HTML to ensure that it contains only supported HTML elements and CSS properties. The API also adds attributes that support OneNote features.

To retrieve the HTML content of a OneNote page, you send a GET request to the page's content endpoint:

GET ../api/v1.0/me/notes/pages/{page-id}/content[?includeIDs=true]

The API returns the converted output HTML that you can use in your app. See Example input and output for an example of input HTML used to create a page and the output HTML that's returned. Output HTML includes all defined data-id values. If includeIDs=true is used, it also includes generated IDs.

Note
When you create a page or get page metadata, the API returns the content endpoint URL of the page in the contentUrl property. To try it out, see POST Pages and GET Pages in the OneNote API interactive reference.

OneNote HTML

The following sections describe the principal elements and attributes of input and output HTML. HTML tag support for pages describes additional requirements for creating OneNote pages.

Body

The HTML content in the page body represents the page content and structure, including image and file resources. The body element can contain the following attributes in the input and output HTML.

Input attributes for the body element

Input attribute	Description
data-absolute-enabled	Indicates whether the input body supports absolutely positioned elements. See Create pages with absolutely positioned elements for more information.
style	The CSS style properties of the body. In the output HTML, input settings may be returned inline on appropriate child elements. Background-color is not currently supported for the body element.

See Make simple captures and Create structure using HTML for more information about creating pages.

Output attributes for the body element

Output attribute	Description
data-absolute-enabled	Indicates whether the body supports absolutely positioned elements. Always true in output HTML.
style	The font-family and font-size properties of the body.

Divs

Divs contain text, images, and other content. A div element can contain the following attributes in the input and output HTML.

Input attributes for div elements

Input attribute	Description
data-id	A reference for the element. Used for page updates.
data-render-fallback	The fallback action if the extraction fails: render (default) or none.
data-render-method	The extraction method to perform, for example: extract.businesscard or extract.recipe.
data-render-src	The content source for the extraction.
style	The position, size, font, and color properties for the div: position (absolute only), left, top, and width properties. (Height is auto-configured for divs.) Used to create an absolutely positioned div, only if the div is a direct child of the body when the body sets data-absolute-enabled="true". Learn more about absolutely positioned elements. Example: <div style="position:absolute;width:360px;top:350px;left:300px" ... /> The CSS style properties of the element. In the output HTML, these values are returned inline on appropriate child elements.

The OneNote API wraps all body content in at least one div. The API creates a default div (data-id="_default") to contain the body content if:

The input body element's data-absolute-enabled attribute is omitted or set to false. In this case, all body content is put in the default div.
The input body element's data-absolute-enabled attribute is true, but the input HTML contains direct children that aren't absolutely positioned div, img, or object elements. In this case, direct children that aren't absolutely positioned div, img, or object elements are put in the default div.

See Create pages with absolutely positioned elements for more information about absolutely positioned divs.

Output attributes for div elements

Output attribute	Description
data-id	A reference for the element. Used for page updates.
id	A unique, generated ID for the element. Returned by GET requests to a page's content endpoint when the includeIDs=true query option is used. Used for page updates.
style	The position and size properties of the div.

Non-contributing divs

When a div element in the input HTML does not contribute to the page structure or carry information that OneNote uses, the API moves the div's content into the parent or default div.

Input HTML that contains a non-contributing, nested div.

<html>
    <head>
        <title>Page Title</title>
    </head>
    <body>
        <div>
            <p>Some text</p>
            <div>
                <p>More text inside a div that doesn't define page structure</p>
            </div>
        </div>
    </body>
</html>

Output HTML. Notice that the div's content was moved to the parent div and the nested <div> tags have been removed. However, the div would have been preserved if it defined any semantic information, such as a data-id.

<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
    <head>
        <title>Page Title</title>
    </head>
    <body data-absolute-enabled="true" style="font-family:Calibri;font-size:11px">
        <div data-id="_default" style="position:absolute;left:48px;top:120px;width:624px">
            <p>Some text</p>
            <p>More text inside a nested div</p>
        </div>
    </body>
</html>

Images

Images on OneNote pages are represented by img elements. An img element can contain the following attributes in the input and output HTML.

Input attributes for img elements

Input attribute	Description
alt	The supplied alt text for the image.
data-id	A reference for the element. Used for page updates.
data-render-src	Either data-render-src or src is required. The webpage to render as a bit-mapped image on the OneNote page: data-render-src="http://..." for a public URL. data-render-src="name:BlockName" for an image part in the Presentation block of a multi-part request. This method is useful when the webpage is more complex than the OneNote page can faithfully render, or when the page requires login credentials. See Capture webpage snapshots for more information.
data-tag	A note tag on the element.
style	The position and size properties for the image: position (absolute only), left, top, width, and height properties. Size can be set on any image. Position properties are used to create an absolutely positioned image, only if the image is a direct child of the body when the body sets data-absolute-enabled="true". Learn more about absolutely positioned elements. Example: <img style="position:absolute;width:360px;top:350px;left:300px" ... /> In the output HTML, the image size is returned separately in width and height attributes.
src	Either src or data-render-src is required. The image to render on the OneNote page: src="http://..." for a URL to a publicly available image on the internet. src="name:BlockName" for a named part in a multi-part request that represents the image.
width, height	The width or height of the image, in pixels but without the px. Example: width="400"

Note
Detecting the image type. The OneNote API automatically detects the input image type, and returns it as the data-fullres-src-type in the output HTML. The API also returns the image type of the optimized image in data-src-type.

See Capture photos and images and Capture webpage snapshots for more information about creating pages that contain images.

Output attributes for img elements

Output attribute	Description
alt	The supplied alt text for the image.
data-id	A reference for the element. Used for page updates.
data-index	The position of the image. For split image support.
data-fullres-src	The endpoint for the version of the image resource that was originally embedded in the page.
data-fullres-src-type	The MIME type of the data-fullres-src resource, for example: image/png or image/jpeg.
data-options	The source type: printout for PDF files or splitimage for all others. Applies only to split images created with the data-render-src attribute.
data-render-original-src	The original source URL of the image, if the source image is from the public internet and was created with the data-render-src attribute.
data-src-type	The MIME type of the src resource, for example: image/png or image/jpeg.
data-tag	A note tag on the element.
id	A unique, generated ID for the element. Returned by GET requests to a page's content endpoint when the includeIDs=true query option is used. Used for page updates.
src	The endpoint for the version of the image resource that has been optimized for web browsers and mobile and tablet form factors.
style	The position properties of the image.
width, height	The width or height of the image, in pixels.

Output HTML examples for images

Output img elements contain endpoints that link to image file resources in the page and the image type, as shown in the following example. You can make separate GET requests to the resource endpoints to retrieve their binary contents.

<img 
    src="https://www.onenote.com/api/v1.0/resources/{image-id}/$value"  
    data-src-type="image/png"
    data-fullres-src="https://www.onenote.com/api/beta/resources/{image-id}/$value"  
    data-fullres-src-type="image/png" ... />

Note
Images won’t render directly in a browser because they are private and require authorization to retrieve them, like the rest of the page contents.

The following examples show the information an img element might contain in the output HTML.

Image with web-ready and high resolution resources

<img
    src="{web-ready-image-resource-url}/$value"
    data-src-type="image/{type}"
    data-fullres-src="{high-resolution-image-resource-url}/$value"
    data-fullres-src-type="image/{type}"
    [data-render-original-src="{original-source-url-or-named-part}"]
    [data-id="{image-id}"]
    [alt="supplied alt text"]
    [width="345"] [height="180"]
    [style="..."] />

Image created by using the data-render-src attribute

<img
    src="{web-ready-image-resource-url}/$value"
    data-src-type="image/{type}"
    data-fullres-src="{high-resolution-image-resource-url}/$value"
    data-fullres-src-type="image/{type}"
    data-render-original-src="{original-source-url-or-named-part}"
    [data-id="{image-id}"]
    [data-index="{index-of-split-image}"]
    [data-options="{printout-or-splitimage}"]
    [alt="supplied alt text"]
    [width="1024"] [height="1900"]
    [style="..."] />

Split images

Images that are created using the data-render-src attribute from a webpage URL or a named part might be split into multiple component images for performance and rendering reasons. Component images are all assigned the same data-id value. Each component image has a zero-based data-index attribute that defines the original vertical layout.

Split image with three component images

<div data-id="multi-component-image" style="position:absolute;left:48px;top:120px;width:624px">
    <img
        src="{image-resource0-url}/$value"
        data-src-type="image/{type}"
        data-fullres-src="{image-resource0-url}/$value" 
        data-fullres-src-type="image/{type}" 
        data-index="0" 
        data-render-original-src=""{original-source-url-or-named-part}"
        data-id="{same-image-id}" ... />
    <img 
        src="{image-resource1-url}/$value" 
        data-src-type="image/{type}" 
        data-fullres-src="{image-resource1-url}/$value" 
        data-fullres-src-type="image/{type}" 
        data-index="1" 
        data-render-original-src="{original-source-url-or-named-part}"
        data-id="{same-image-id}" ... />
    <img 
        src="{image-resource2-url}/$value" 
        data-src-type="image/{type}" 
        data-fullres-src="{image-resource2-url}/$value" 
        data-fullres-src-type="image/{type}" 
        data-index="2" 
        data-render-original-src=""{original-source-url-or-named-part}"
        data-id="{same-image-id}" ... />
</div>

Because users can move the images on the page, the returned indexes might be out of order. Ordering should be in top to bottom y-order, then left to right x-order if there are y-order conflicts.

Objects

OneNote pages can contain file attachments represented by object elements. An object element can contain the following attributes in the input and output HTML.

Note
The OneNote API can also render file content as images in a page when the file is sent as an image and uses the data-render-src attribute. Example: <img data-render-src="name:BlockName" ... />

Input attributes for object elements

Input attribute	Description
data	Required. The name of the part that represents the file in the multi-part request.
data-attachment	Required. The file name.
data-id	A reference for the element. Used for page updates.
style	The position and size properties for the object: position (absolute only), left, top, and width properties. Used to create an absolutely positioned object, only if the object is a direct child of the body when the body sets data-absolute-enabled="true". Learn more about absolutely positioned elements. Example: <object style="position:absolute;top:350px;left:300px" ... />
type	Required. The standard MIME file type. Known file types display the icon associated with the file type on the OneNote page. Unknown file types display a generic file icon.

See Capture embedded files and Capture and embed PDF files for more information about creating pages that contain file attachments.

Output attributes for object elements

Output attribute	Description
data	The endpoint for the file resource.
data-attachment	The file name.
data-id	A reference for the element. Used for page updates.
id	A unique, generated ID for the element. Returned by GET requests to a page's content endpoint when the includeIDs=true query option is used. Used for page updates.
style	The position properties of the object.
type	The standard MIME file type.

Output HTML example for objects

Output object elements contain endpoints that link to the file resources in the page. You can make separate GET requests to these resource endpoints to retrieve their binary contents.

<object
    data="http://www.onenote.com/api/v1.0/resources/{file-id}/$value"
    data-attachment="fileName.pdf" 
    type="application/pdf" 
    [style="..."] />

Paragraphs and headings

Paragraphs, headings, and other text containers can contain the following attributes in the input and output HTML.

Input attributes for text containers

Input attribute	Description
data-id	A reference for the element. Used for page updates.
data-tag	A note tag on a p or h1 - h6 element.
style	The CSS style properties of the element.

Output attributes for text containers

Output attribute	Description
data-id	A reference for the element. Used for page updates.
data-tag	A note tag on a p or h1 - h6 element.
id	A unique, generated ID for the element. Returned by GET requests to a page's content endpoint when the includeIDs=true query option is used. Used for page updates.
style	The CSS style properties of the element. In the output HTML, these values may be returned on inline on appropriate child elements or span elements.

The following examples show input HTML that uses different ways to define styles on text containers and the output HTML that's returned.

Input HTML with styles defined using inline character styles, in the start tag, and within a span element.

<h1>Heading <i>One</i> text</h1>
<p style="font-size:8pt;color:green;font-family:Courier;text-align:center">Some text</p>
<p>Some <span  style="font-size:16px;color:#ff0000;font-family:Segoe UI Black">more</span> text</p>

Output HTML with the character style and the font settings in the start tag returned as inline CSS styles on span elements.

<h1 style="font-size:16pt;color:#1e4e79;margin-top:11pt;margin-bottom:11pt">Heading <span style="font-style:italic">One</span> text</h1>
<p style="text-align:center"><span style="font-family:Courier;font-size:8pt;color:green">Some text</span></p>
<p>Some <span style="font-family:Segoe UI Black;font-size:12pt;color:red">more</span> text</p>

Lists

Lists are represented as ol or ul elements that can contain li elements.

Lists and list items can contain the following attributes in the input and output HTML.

Input attributes for lists

Input attribute	Description
data-id	A reference for the element. Used for page updates.
data-tag	A note tag on a ul, ol, or li element.
style	The list-style-type and the CSS style properties for the list or list item.

Output attributes for lists

Output attribute	Description
data-id	A reference for the element. Used for page updates.
data-tag	A note tag on a span in a li element.
id	A unique, generated ID for the element. Returned by GET requests to a page's content endpoint when the includeIDs=true query option is used. Used for page updates.
style	The list-style-type and CSS style properties of the element. In the output HTML, settings at the list-level are returned on list items. Default properties are not returned.

The OneNote API supports the following list styles:

Ordered list	Unordered list
none decimal (default) lower-alpha lower-roman upper-alpha upper-roman	none disc (default) circle square

You can apply global styles for a list on the ol or ul element in the input HTML, but styles are returned on the li elements.

Homogenous list style

This example shows input HTML that sets the list style type on the ol element and CSS styles on individual list items.

<ol style="list-style-type:upper-roman;color:blue">
    <li style="font-weight:bold">Jacksonville</li>
    <li style="text-decoration:line-through">Orlando</li>
    <li style="font-family:Courier">Naples</li>
</ol>

This is the output HTML. Notice that styles are returned inline on the individual li or span elements.

<ol>
    <li style="list-style-type:upper-roman"><span style="color:blue;font-weight:bold">Jacksonville</span></li>
    <li style="list-style-type:upper-roman"><span style="color:blue;text-decoration:line-through">Orlando</span></li>
    <li style="list-style-type:upper-roman"><span style="font-family:Courier;color:blue">Naples</span></li>
</ol>

Variable list styles

This example shows input HTML that sets different list style types on the li elements.

<ul style="font-style:italic">
    <li style="list-style-type:square">square style</li>
    <li style="list-style-type:circle">circle style</li>
    <li style="list-style-type:disc">disc style (default)</li>
</ul>

This is the output HTML. Notice that styles are returned inline on the individual li or span elements.

<ul>
    <li style="list-style-type:square"><span style="font-style:italic">square style</span></li>
    <li style="list-style-type:circle"><span style="font-style:italic">circle style</span></li>
    <li><span style="font-style:italic">disc style (default)</span></li>
</ul>

Tables

Tables are represented as table elements that can contain tr and td elements. Nested tables are supported.

Tables can contain the following attributes in the input and output HTML. The OneNote API does not support rowspan or colspan attributes.

Input attributes for tables

Input attribute

Description

data-id

A reference for the element. Used for page updates.

style

The CSS style properties of the element, and also:

border. Can be either 0px or 1px.
width. Supported by table and td as pixels or percentage of page width. Example: width="100px" or width="60%"

Output attributes for tables

Output attribute	Description
data-id	A reference for the element. Used for page updates.
id	A unique, generated ID for the element. Returned by GET requests to a page's content endpoint when the includeIDs=true query option is used. Used for page updates.
style	The CSS style properties of the element.

The following examples show input HTML that uses different ways to define styles on tables and the output HTML that's returned.

Input HTML with optional settings at different levels.

<table style="border:0px;width:500px;background-color:green">
    <tr> 
        <td>Cell 1</td> 
        <td>Cell 2</td> 
        <td>Cell 3</td> 
    </tr> 
    <tr style="background-color:blue"> 
        <td style="text-align:right;background-color:red">Left</td> 
        <td style="text-align:center">Middle</td> 
        <td>Right</td> 
    </tr> 
</table>

Output HTML with CSS styles returned inline on the td elements.

<table style="border:0px">
    <tr>
        <td style="background-color:green;width:166;border:0px">Cell 1</td>
        <td style="background-color:green;width:166;border:0px">Cell 2</td>
        <td style="background-color:green;width:166;border:0px">Cell 3</td>
    </tr>
    <tr>
        <td style="background-color:red;width:166;border:0px;text-align:right">Left</td>
        <td style="background-color:blue;width:166;border:0px;text-align:center">Middle</td>
        <td style="background-color:blue;width:166;border:0px">Right</td>
    </tr>
</table>

Styles

The OneNote API supports the following inline CSS style properties for elements in the page body, such as body, div, p, li, and span.

Property	Example
background-color	style="background-color:#66cc66" (defaults to white) Both hexadecimal format and named colors are supported.
color	style="color:#ffffff" (defaults to black)
font-family	style="font-family:Courier" (defaults to Calibri)
font-size	style="font-size:10pt" (defaults to 11pt) The OneNote API accepts font size in pt or px, but converts px to pt. Decimal values are rounded to the nearest n.0pt or n.5pt.
font-style	style="font-style:italic" (normal or italic only)
font-weight	style="font-weight:bold" (normal or bold only)
strike-through	style="text-decoration:line-through"
text-align	style="text-align:center" (for block elements only)
text-decoration	style="text-decoration:underline" (none or underline only)

The following inline character styles and are also supported:

<strike>
<del>

<cite>

Example input and output HTML

The following image shows a simple page that was created with the OneNote API.

This is the input HTML that was sent in the request body to create the page.

HTML

<html lang="en-US">
    <head>
        <title>Sample Study Notes</title>
        <meta name="created" content="2015-01-01T01:01"/>
    </head>
    <body>
        <h1>American History 101: Moon Landing</h1>
        <p>First moon landing - July 20, 1969 with Apollo 11 (Eagle)</p>
        <br />
        <p><b>Apollo 11 Astronauts</b></p>
        <table>
            <tr>
                <td>Neil Armstrong</td>
                <td>Commander</td>
            </tr>
            <tr>
                <td>Buzz Aldrin</td>
                <td>LM Pilot</td>
            </tr>
            <tr>
                <td>Michael Collins</td>
                <td>Command Module Pilot</td>
            </tr>
        </table>
        <img alt="Apollo 11 commemorative stamp." src="http://upload.wikimedia.org/wikipedia/commons/a/a4/First_Man_on_Moon_1969_Issue-10c.jpg"  width="400"/>
        <p>References:</p>
        <p><a href="http://en.wikipedia.org/wiki/Apollo_11">http://en.wikipedia.org/wiki/Apollo_11</a></p>
        <p><a href="http://www.nasa.gov/mission_pages/apollo/missions/apollo11.html">http://www.nasa.gov/mission_pages/apollo/missions/apollo11.html</a></p>
    </body>
</html>

This is the output HTML that the OneNote API returns when you get the page content.