@notesnook-importer/onenote

Microsoft OneNote .one / .onetoc2 / .onepkg parser and HTML converter. Reads OneNote files directly — no OneNote installation or export step required. Implemented as a from-scratch parser for the OneNote desktop file format ([MS-ONESTORE] / [MS-ONE]) with an HTML converter modeled after one2html.

Part of the Notesnook Importer monorepo.

Install

npm install @notesnook-importer/onenote

Requires @notesnook-importer/core (peer dependency for HTML element types).

Supported file formats

| Format | Notes | | --- | --- | | .one | OneNote sections (OneNote 2016 / 2019 / LTSC desktop format). | | .onetoc2 | Notebook tables of contents. Used to build the notebook hierarchy. | | .onepkg | OneNote package (CAB archive containing a notebook). Supports uncompressed, MSZIP and LZX/LZXD compression. |

Not supported: files in the FSSHTTPB packaging format (OneDrive web UI downloads), the legacy OneNote 2007 format, and encrypted sections without a password.

Getting OneNote files

| Source | How to get the files | | --- | --- | | OneNote desktop (2016, 2019, LTSC) | Export as a .onepkg package via File → Export → Notebook → OneNote Package, or select files/folders directly. | | OneDrive | Download the notebook folder from OneDrive (contains .onetoc2 + .one section files). | | OneNote for Windows 10/11 | Export each section as a .one file via Settings → Export. |

Zip archives containing any of the above are unpacked automatically.

Keep the folder structure. A .onetoc2 file only imports the .one files in the same directory (and subdirectories for section groups).

What it does

• Parses .onetoc2 notebooks to resolve section ordering and section groups
• Section groups become nested folders; each page becomes a note
• Converts page content to Notesnook HTML, preserving visual layout (positioning, indentation, sizes)

Notebook structure

• Notebooks (.onetoc2) and their section ordering
• Section groups, including nested groups, imported as nested notebooks
• Standalone sections (.one files without a notebook)

Pages

• Page titles (including title formatting and HYPERLINK marker cleanup)
• Created & last modified dates, author, and page level (sub-pages)
• Pages with no title fall back to Untitled Page N; empty pages are skipped

Text & formatting

• Rich text paragraphs with per-character text runs
• Bold, italic, underline, strikethrough, superscript, subscript
• Font family, font size, font color, text highlight color
• Paragraph alignment (left/center/right) and spacing
• Hyperlinks — both the hidden \uFDDF HYPERLINK marker format and plain http(s):// text

Lists & note tags

• Numbered lists (decimal, upper/lower roman, upper/lower latin) and bulleted lists
• List restart values, bullet fonts/colors, Wingdings bullet fixes
• Note tags & to-do checkboxes: 30+ checkable shapes render as checkbox icons
• Other tag icons (star, question mark, priority, contact, light bulb, etc.)
• Note tag label highlight/text colors applied to content

Tables

• Tables with row/column counts, column widths, locked columns, visible borders
• Cell background colors and cell contents (including nested lists and note tags)

Images & attachments

• Embedded images extracted and imported as attachments (with OCR alt text and width/height constraints)
• Embedded files (documents, audio, video) imported as attachments with original file names

Ink (handwriting)

• Handwritten ink rendered as inline SVG strokes, preserving stroke color, width, pen tip style, and page position
• Ink embedded inside text paragraphs (inline handwriting, spaces, line breaks)

Encrypted sections

Password-protected sections are fully supported via [MS-OFFCRYPTO] Agile Encryption (AES-256-CBC with SHA-512 key derivation).

Providing a password — Provider API:

settings.options = {
  onenote: {
    getPassword: async (filename) => {
      return passwords[filename];
    }
  }
};

Providing a password — Direct API:

const section = await parseOneNoteSection(bytes, "My Section", "s3cret");
const notebook = await parseOneNoteNotebook(tocBytes, resolveFile, "s3cret");

Not supported

• FSSHTTPB/OneDrive packaging format — files downloaded via the OneDrive web UI in "package" format
• OneNote 2007 (or earlier) legacy format and alternative packaging
• Encrypted sections without a password — skipped with a warning; provide a password to decrypt
• Math/equation formatting — imported as plain text
• Ink handwriting recognition (OCR) text — recognized text is parsed but not added to the note
• Audio/video recordings — imported as attachment only when embedded; external onefiles references are skipped
• Version history & conflict pages — only the current revision is imported
• Section/notebook colors — read but not applied to notes yet

Usage

import {
  parseOneNoteSection,
  parseOneNoteNotebook,
  parseOneNoteNotebookToc,
  extractOnepkg,
  isOnepkg,
  renderPage,
  sniffOneNoteFileType,
  OneNoteEncryptedError
} from "@notesnook-importer/onenote";

License

GPL-3.0-or-later