Skip to content

docs: refresh README for v1.3.0 #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jli-software merged 1 commit into from
Sep 3, 2026
Merged

docs: refresh README for v1.3.0 #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
197 changes: 142 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,79 +4,166 @@

# OneNote Backup Exporter

A Windows desktop application to export OneNote notebooks to portable formats.
Talks directly to OneNote Desktop via the COM API.
A Windows desktop application for exporting complete OneNote notebooks or selected sections
to backup and offline-reading formats. It communicates directly with OneNote Desktop through
Microsoft's COM API.

![version](https://img.shields.io/badge/version-1.3.0-blueviolet?style=flat-square)
![version](https://img.shields.io/github/v/release/jli-software/OneNoteBackupExporter?display_name=tag&style=flat-square&color=8a2be2)
![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-0078D7?style=flat-square&logo=windows&logoColor=white)
![license](https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square)
![built with](https://img.shields.io/badge/built%20with-.NET%2010%20%2F%20WPF-512BD4?style=flat-square&logo=dotnet&logoColor=white)

</div>

---
## Download

![OneNote Backup Exporter main window](demoScreenshot.png)
[Download the latest Windows x64 installer](https://github.com/jli-software/OneNoteBackupExporter/releases/latest/download/OneNoteBackupExporter_Setup.exe)
or view the [latest release](../../releases/latest).

## Download
The installer is self-contained, so users do not need to install the .NET runtime separately.
The application version and short build revision are available from the **?** button in the
header.

[Download the latest installer](https://github.com/jli-software/OneNoteBackupExporter/releases/latest/download/OneNoteBackupExporter_Setup.exe)
or view the [latest release](../../releases/latest). The public asset names remain stable
across releases:
Published assets use stable names across releases:

- `OneNoteBackupExporter_Setup.exe`
- `OneNoteBackupExporter_Setup.exe.sha256`

The matching [SHA-256 checksum](https://github.com/jli-software/OneNoteBackupExporter/releases/latest/download/OneNoteBackupExporter_Setup.exe.sha256)
can be used to verify the download. The installed application version is available in the
About dialog.
## Highlights

## Automated builds and releases
- Export complete notebooks or expand a notebook and select individual sections.
- Create full-fidelity OneNote packages, browser-readable HTML, PDF, or XPS files.
- Preserve OneNote section-group structure when exporting sections or HTML pages.
- Copy an existing local OneNote backup folder when that option is available.
- Protect previous exports with staging files or directories until the new export succeeds.
- Recover once from supported temporary OneNote COM/RPC connection failures.
- Cancel cooperatively without closing or terminating OneNote Desktop.

GitHub Actions runs the automated tests, builds a self-contained Windows x64 application,
and compiles the Inno Setup installer for every pull request and every push to `main`. The
installer and its SHA-256 checksum are available as workflow artifacts for 14 days.
## Requirements

To publish a release:
- Windows 10 or Windows 11, 64-bit
- OneNote Desktop with the COM API available, such as the desktop app included with
Microsoft 365 or a supported Office installation

1. Update `<Version>` in `OneNoteExporter.csproj` and commit the change.
2. Create and push a matching tag, for example `v1.3.0`.
3. GitHub Actions builds the installer, creates the GitHub release with generated notes, and
uploads the installer plus checksum automatically.
The retired **OneNote for Windows 10** UWP app does not expose the required COM API and is not
supported. Open OneNote Desktop at least once before using the exporter.

The tag and project versions must match; otherwise the release build fails without publishing.
## Quick start

## Requirements
1. Open OneNote Desktop, allow cloud notebooks to finish syncing, and unlock any protected
sections you want to export.
2. Start OneNote Backup Exporter. The header should report
**OneNote Desktop (COM API available)**.
3. Select one or more notebooks. To export specific sections instead, choose **Sections** on a
notebook and select the required sections.
4. Choose a destination folder and export format.
5. Select **Export** and keep OneNote open until the result is shown.

Exports can take several minutes for large or cloud-hosted notebooks. Progress messages indicate
which notebook, section, or HTML page is currently being processed.

## Export formats

| Format | Selection | Result and intended use |
|---|---|---|
| OneNote Package (`.onepkg`) | Notebook or section | Recommended backup format. Preserves OneNote content and can be imported into OneNote. |
| HTML Web Pages | Notebook or section | Offline browser copy with generated notebook and section indexes, individual `.htm` pages, and companion assets. |
| PDF Document (`.pdf`) | Notebook or section | Widely readable rendered output. For large notebooks, section-by-section export is safer. |
| XPS Document (`.xps`) | Notebook or section | Rendered output with good layout preservation. For large notebooks, section-by-section export is safer. |
| Local Backup Copy | All notebooks | Copies the complete local OneNote backup directory. Manual notebook selections are ignored. |

### HTML output

HTML exports create a `<Notebook>__<stable-id>_html` directory containing an `index.html` start
page. Each OneNote page is published separately because OneNote's COM API provides reliable HTML
publishing at page level.

- Complete notebook exports link to all exported pages from generated notebook and section
indexes.
- Selected-section exports create or refresh the notebook index with the section indexes that
are present in the destination.
- Section groups remain nested directories.
- Images and other companion assets written by OneNote are kept beside the exported pages.
- Stable IDs prevent same-named notebooks, sections, and pages from overwriting one another.
- Re-exporting replaces the previous HTML directory only after every page and index succeeds.

HTML is designed for offline reading. It is not a re-importable substitute for `.onepkg`.
OneNote subpage levels are currently listed as normal pages in the generated indexes.

### Large PDF and XPS exports

OneNote does not expose notebook size through its COM interface, and its renderer can fail on
large whole-notebook PDF or XPS exports. Before such an export, the application offers three
choices:

1. export every unlocked section separately (recommended);
2. create a complete `.onepkg` backup instead; or
3. attempt the whole-notebook rendered export.

Section-by-section output preserves section groups as folders and uses collision-safe names.

### Local backup copy

This option copies all files from OneNote's local backup directory and ignores notebook
selection. Version 1.3 currently checks the German OneNote 16.0 backup path:

`%LOCALAPPDATA%\Microsoft\OneNote\16.0\Sicherung`

The option is disabled when that directory does not exist, cannot be read, or is empty.

## Reliability and cancellation

- OneNote COM work runs serially on a dedicated STA thread.
- Single-file and HTML exports are written to protected staging locations. An existing good
export is replaced only after the new result is complete.
- Temporary supported COM/RPC failures receive one bounded reconnection and retry attempt.
- **Cancel** never closes or terminates OneNote. A synchronous OneNote `Publish` call cannot be
interrupted safely; cancellation takes effect as soon as OneNote returns control.

## Known limitations

- Password-protected sections must be unlocked in OneNote before export.
- OneDrive and SharePoint notebooks must be fully synced before export.
- Export fidelity and supported page content are ultimately determined by OneNote's own
publishing engine.
- Large whole-notebook PDF/XPS exports can still fail inside OneNote; use the recommended
section-by-section mode or `.onepkg`.
- HTML indexes currently flatten OneNote subpage levels.
- The local backup-copy option currently uses the German `Sicherung` directory shown above.

## Verify a download

Download the matching
[SHA-256 checksum](https://github.com/jli-software/OneNoteBackupExporter/releases/latest/download/OneNoteBackupExporter_Setup.exe.sha256)
and verify the installer in PowerShell:

```powershell
Get-FileHash .\OneNoteBackupExporter_Setup.exe -Algorithm SHA256
Get-Content .\OneNoteBackupExporter_Setup.exe.sha256
```

The two hashes should match.

## Build from source

The project requires the .NET 10 SDK on Windows. Inno Setup is optional unless an installer is
needed.

```powershell
dotnet test .\tests\OneNoteExporter.Tests\OneNoteExporter.Tests.csproj -c Release
dotnet publish .\OneNoteExporter.csproj -c Release -r win-x64 --self-contained true
```

Run `build.ps1` to create the self-contained application in `build` and, when Inno Setup is
installed, `artifacts\OneNoteBackupExporter_Setup.exe`.

## Automated builds and releases

GitHub Actions runs the tests, publishes the self-contained Windows x64 application, and compiles
the installer for every pull request and every push to `main`. The installer and SHA-256 checksum
remain available as workflow artifacts for 14 days.

Pushing a semantic-version tag such as `vX.Y.Z` publishes a GitHub release when the tag version
matches `<Version>` in `OneNoteExporter.csproj`. The release contains the installer and checksum.

- Windows 10 or 11 (64-bit)
- OneNote Desktop 2016 or later (including Microsoft 365)

The Microsoft Store version of OneNote is not supported.

## Export Formats

| Format | Notes |
|---|---|
| OneNote Package (.onepkg) | Recommended. Full-fidelity, re-importable into OneNote. |
| HTML Web Pages | Browser-readable page folders plus generated notebook/section indexes. OneNote writes each page as `.htm` with any companion assets beside it. |
| XPS Document (.xps) | Good layout preservation. Large whole notebooks can be split into safer per-section exports. |
| PDF Document (.pdf) | Universal, slightly lower quality on complex pages. Large whole notebooks can be split into safer per-section exports. |
| Local Backup Copy | Copies the raw backup folder from `%LOCALAPPDATA%\Microsoft\OneNote\16.0\Sicherung`. Fastest option, all notebooks at once. |

## Notes

- Password-protected sections cannot be exported. Unlock them in OneNote first.
- Cloud notebooks (OneDrive, SharePoint) must be synced before export. Large notebooks can take several minutes.
- HTML exports create a `<Notebook>__<stable-id>_html` folder with an `index.html` start
page. The stable suffix prevents same-named notebooks from overwriting each other. Complete
notebook exports link directly to every page; selected-section exports create or refresh
the notebook start page with links to the available section indexes. Each OneNote page is
published separately so notebook and section selections work even though OneNote's COM
API only provides reliable HTML publishing at page level. Section groups remain folders;
OneNote subpage levels are currently listed as normal pages. HTML is intended for offline
browser access and is not a re-importable replacement for `.onepkg`.
- OneNote does not expose notebook size through its COM interface. Before a whole-notebook
PDF/XPS export, the app therefore offers to export each section separately (recommended),
create a complete `.onepkg` backup, or consciously try the whole rendered export. Split
exports include all exportable, unlocked sections and preserve section groups as folders
to avoid filename collisions. Use `.onepkg` when a single complete backup is required.
See [CHANGELOG.md](CHANGELOG.md) for version history.
Loading