Skip to content

Latest commit

 

History

History
284 lines (189 loc) · 20.1 KB

README.md

File metadata and controls

284 lines (189 loc) · 20.1 KB
Raw

Convert OneNote to MarkDown

github-actions github-release

Ready to make the step to Markdown and saying farewell to your OneNote, EverNote or whatever proprietary note taking tool you are using? Nothing beats clear text, right? Read on!

The powershell script ConvertOneNote2MarkDown-v2.ps1 will utilize the OneNote Object Model on your workstation to convert all OneNote pages to Word documents and then utilizes Pandoc to convert the Word documents to Markdown (.md) format.

Summary

  • Choose between converting a specific notebook or all notebooks in OneNote. Only notebooks which are open and synchronized in OneNote can be converted.
  • Choose to do a dry run or run the actual conversion.
  • Create a folder structure for your Notebooks and Sections
    • Process pages that are in sections at the Notebook, Section Group and all Nested Section Group levels
  • Choose between creating subfolders for subpages (e.g. Page\Subpage.md) or appending prefixes (e.g. Page_Subpage.md)
  • Specify a value between 32 and 255 as the maximum length of markdown file names, and their folder names (only when using subfolders for subpages (e.g. Page\Subpage.md). A lower value can help avoid hitting file and folder name limits of 255 bytes on file systems. A higher value preserves a longer page title. If using page prefixes (e.g. Page_Subpage.md), it is recommended to use a value of 100 or greater.
  • Choose between putting all media (images, attachments) in a central /media folder for each notebook, or in a separate /media folder in each folder of the hierarchy
    • Symbols in media file names removed for link compatibility
    • Updates media references in the resulting .md files, generating relative references to the media files within the markdown document
  • Choose between discarding or keeping intermediate Word files. Intermediate Word files are stored in a central notebook folder.
  • Choose between converting from existing .docx (90% faster) and creating new ones - useful if just want to test differences in the various processing options without generating new .docxeach time
  • Choose between naming .docx files using page ID and last modified epoch date e.g. {somelongid}-1234567890.docx or hierarchy e.g. <sectiongroup>-<section>-<page>.docx
  • specify Pandoc output format and any optional extensions, defaulting to Pandoc Markdown format which strips most HTML from tables and using pipe tables. Customize this to get the desired Markdown flavor. See more details on these options here:
    • markdown (Pandoc Markdown)
    • commonmark (CommonMark Markdown)
    • gfm (GitHub-Flavored Markdown), or the deprecated and less accurate markdown_github; use markdown_github only if you need extensions not supported in gfm.
    • markdown_mmd (MultiMarkdown)
    • markdown_phpextra (PHP Markdown Extra)
    • markdown_strict (original unextended Markdown)
    • Improved headers, with title now as a # heading, standardized DateTime format for created and modified dates, and horizontal line to separate from rest of document
  • Choose whether to clear extra newlines between unordered (bullet) and ordered (numbered) list items, non-breaking spaces from blank lines, and > after unordered lists, which are created when converting with Pandoc
  • Choose whether to remove \ escape symbol that are created when converting with Pandoc
  • Choose whether to use Line Feed (LF) or Carriage Return + Line Feed (CRLF) for new lines
  • Choose whether to include a .pdf export alongside the .md file. .md does not preserve InkDrawing (i.e. overlayed drawings, highlights, pen marks) absolute positions within a page, but a .pdf export is a complete page snapshot that preserves InkDrawing absolute positions within a page.
  • Detailed logs. Run the script with -Verbose to see detailed logs of each page's conversion.

Known Issues

  1. If there are any collapsed paragraphs in your pages, the collapsed/hidden paragraphs will not be exported in the final .md file
    • You can use the included Onetastic Macro script to automatically expand all paragraphs in each Notebook
    • Download Onetastic here and, once installed, use New Macro > File > Import to install the attached .xml macro file within Onetastic
  2. Password protected sections should be unlocked before continuing, the Object Model does not have access to them if you don't
  3. You should start by "flattening" all InkDrawing (i.e. pen/hand written elements) in your onennote pages. Because OneNote does not have this function you will have to take screenshots of your pages with pen/hand written notes and paste the resulting image and then remove the scriblings. If you are a heavy pen user this is a very cumbersome.
    • Alternatively, if you are converting a notebook only for reading sake, and want to preserve all notes layout, instead of flattening all InkDrawing manually, you may prefer to export a .pdf which preserves the full apperance and layout of the original note (including InkDrawing). Simply use the config option $exportPdf = 2 to export a .pdf alongisde the .md file.
  4. While running the conversion OneNote will be unusable and it is recommended to walk away and have some coffee as the Object Model might be interrupted if you do anything else.
  5. Linked file object in .md files are clickable in VSCode, but do not open in their associated program, you will have to open the files directly from the file system.

Requirements

Usage

  1. Clone or download the repository to acquire the powershell script.

  2. Start the OneNote application (may require opening as Adminstrator in some cases). Keep OneNote open during the conversion.

  3. It is advised that you install Onetastic and the attached macro, which will automatically expand any collapsed paragraphs in the notebook. They won't be exported otherwise.

    • To install the macro, click the New Macro Button within the Onetastic Toolbar and then select File > Import and select the .xml macro included in the release.
    • Run the macro for each Notebook that is open

  4. It is highly recommended that you use VS Code, and its embedded Powershell terminal, as this allows you to edit and run the script, as well as check the results of the .md output all in one window.

  5. If you prefer to use a configuration file, rename config.example.ps1 to config.ps1 and configure options in config.ps1 to your liking.

    • You may like to use $dryRun = 1 to do a dry run first. This is useful for trying out different settings until you find one you like.

  6. Whatever you choose, open Powershell as Administrator (or VSCode as Administrator, with Powershell as the integrated terminal).

    • In Powershell, first navigate to the folder containing the script:
    cd "C:\path\to\ConvertOneNote2Markdown"
    • Then run the script:
    .\ConvertOneNote2MarkDown-v2.ps1
    • If you would like to see detailed logs about the conversion process, use the -Verbose switch:
    .\ConvertOneNote2MarkDown-v2.ps1 -Verbose
    • By default, the script does not terminate on any errors during conversion, but it keeps continuing. If you would like the script to terminate immediately on any error it encounters, use the -ErrorAction Stop switch (That way, if the script finishes without errors, you can be sure the entire conversion process went perfectly):
    .\ConvertOneNote2MarkDown-v2.ps1 -ErrorAction Stop
    Set-ExecutionPolicy Bypass -Scope Process -Force
    • If you see any other errors, check the FAQ.

  7. If you chose to use a configuration file config.ps1, skip to the next step. If you did not choose to use a configuration file, the script will ask you for configuration interactively.

    • It starts off asking whether to do a dry run. This is useful for trying out different settings until you find one you like.
    • It will ask you for the path to store the markdown folder structure. Please use an empty folder. If using VS Code, you might not be able to paste the filepath - right click on the blinking cursor and it will paste from clipboard. Use a full absolute path.
    • Read the prompts carefully to select your desired options. If you aren't actively editing your pages in OneNote, it is highly recommended that you don't delete the intermediate word docs, as they take 80+% of the time to generate. They are stored in their own folder, out of the way. You can then quickly re-run the script with different parameters until you find what you like.

  8. Sit back and wait until the process completes.

  9. To stop the process at any time, press Ctrl+C.

  10. If you like, you can inspect some of the .md files prior to completion. If you're not happy with the results, stop the process, delete the .md and media folders and re-run with different configuration options.

    • If you want to convert to Obsidian Markdown, try any of these recommendations (see here, here):
    $conversion = 'markdown-simple_tables-multiline_tables-grid_tables+pipe_tables-bracketed_spans+native_spans+startnum'
$conversion = 'markdown_mmd-simple_tables-multiline_tables-grid_tables+pipe_tables-mmd_link_attributes'
    • If you want to convert to GitHub Flavored Markdown, try this (see here):
    $conversion = 'gfm+pipe_tables-raw_html'
    • If you do not want the line of image dimensions after each image, e.g. {width="12.072916666666666in" height="6.65625in"} in markdown, try this (see here):
    $conversion = 'gfm+pipe_tables-raw_html'

Results

The script will log any errors encountered during and at the end of its run, so please review, fix and run again if needed.

If you are satisfied check the results with a markdown editor like VSCode. All images should popup just right in the Preview Pane for Markdown files.

Recommendations

  1. I'd like to strongly recommend the VS Code Foam extension, which pulls together a selection of markdown-related extensions to become a comprehensive knowledge management tool.
  2. I'd also like to recommend Obsidian.md, which is another fantastic markdown knowledge management tool.
  3. Some other VSCode markdown extensions to check out are:

Note: The bottom three are not really markdown related but are quite obvious.

code `
  --install-extension davidanson.vscode-markdownlint `
  --install-extension ms-vscode.powershell-preview `
  --install-extension jebbs.markdown-extended `
  --install-extension telesoho.vscode-markdown-paste-image `
  --install-extension redhat.vscode-yaml `
  --install-extension vscode-icons-team.vscode-icons `
  --install-extension ms-vsts.team

FAQ

Q: How to install and run Powershell 7.0.x?

A: To install Powershell 7.0.13 (the highest supported version of Powershell) without overridding any existing version of Powershell Core on your system, download PowerShell-7.0.13-win-x64.zip (validate its checksum here), extract it to a directory C:\PowerShell-7.0.13-win-x64, and run C:\PowerShell-7.0.13-win-x64\pwsh.exe.

To uninstall after your are done converting, simply delete the C:\PowerShell-7.0.13-win-x64 directory.

Q: Why is Powershell Core 7.1 and above unsupported?

A: Powershell 7.1.x and above no longer supports loading Win32 GAC Assemblies, which is needed for interacting with the OneNote Desktop APIs. It is very unlikely that Microsoft will add support for later Powershell Core versions, since Win32 is starting to become deprecated.

Q: How to install Pandoc?

A: Pandoc can be installed in any of the following ways:

  • Download pandoc Windows .msi installer. During installation, ensure Pandoc is installed for all users (by checking the box Install for all users of thie machine), which is needed for Pandoc to be available to Administrator.
  • Use Chocolatey to install the Pandoc package on Windows.

After installing, ensure to restart Powershell or the computer for Pandoc to be set correctly in PATH.

Q: Error(s) when opening OneNote as Administrator

A: If there are errors opening OneNote as Administrator, just open it normally without Administrator permissions. A user has reported successful conversion with only Powershell opened as Administrator. See case.

Q: Some notebooks are not detected / converted

A: The script cannot detect notebooks which are not yet open in OneNote. Use File > Open in OneNote to open all OneNote notebooks that you want to convert, and ensure they are all fully synchronized before running the conversion. This applies to local OneNote notebooks and cloud OneNote notebooks (E.g. OneDrive or Microsoft Teams).

Q: Page attachments (files, images) are missing or corrupt during conversion

Cause: Possible page content bug.

A: Create a new section, copy pages into it, run the script again. See case, which is similar to this case.

Error: File ConvertOneNote2Markdown.ps1 cannot be loaded because running scripts is disabled on this system.

A: Windows disables Powershell (.ps1) scripts by default for security reasons. To allow running .ps1 scripts temporarily only for the current Powershell session, run:

Set-ExecutionPolicy Bypass -Scope Process -Force

Error: Error HRESULT E_FAIL has been returned from a call to a COM component

Cause: Powershell 7.1.x and above does not support loading Win32 GAC Assemblies.

Solution: Use a version of Powershell between 5.x and 7.0.x. See here.

Error: 80080005 Server execution failed (Exception from HRESULT: 0x80080005(CO_E_SERVER_EXEC_FAILURE)

Cause: Mismatch in security contexts of Powershell and OneNote.

Solution: Ensure both Powershell and OneNote are run under the same user privileges. An easy way is to run both Powershell and OneNote as Administrator.

Error: Unable to find type [Microsoft.Office.InterOp.OneNote.HierarchyScope]

Cause: Mismatch in security contexts of Powershell and OneNote.

Solution: Ensure both Powershell and OneNote are run under the same user privileges. An easy way is to run both Powershell and OneNote as Administrator.

Error: Exception calling "Publish" with "4" argument(s): "Class not registered"

Cause: Microsoft Word is not installed.

Solution: Ensure Microsoft Word is installed.

Error: Exception: Exception calling "Publish" with "4" argument(s): "Server execution failed Server execution failed"

Cause: Microsoft Word plugin(s) causing publishing to .docx to fail. E.g. zotero plugin (see case).

Solution: Disable all Microsoft Word plugins before running the conversion.

Error: Exception: Exception calling "Publish" with "4" argument(s): "0x80042006"

Cause 1: Mismatch in security contexts of Powershell and OneNote.

Solution 1: Ensure both Powershell and OneNote are run under the same user privileges. An easy way is to run both Powershell and OneNote as Administrator.

Cause 2: $notesdestpath is not an absolute path.

Solution 2: Use an absolute path for $notesdestpath.

Error: Exception calling "Publish" with "4" argument(s): "The RPC server is unavailable. (Exception from HRESULT: 0x800706BA)"

Cause: Windows Defender could be blocking pandoc.exe. See case.

Solution: Disable Windows Defender. Click Start > Windows Security, under Virus and threat protection > Exclusions click Add or remove exclusions, click Add an exclusion and browse to C:\Program Files\Pandoc\pandoc.exe. Then retry the conversion.

If pandoc.exe is still blocked, you might try to turn off settings under Virus and threat protection, App and browser control, and Device Security.

Error: Exception calling "Publish" with "4" argument(s): "The remote procedure call failed. (Exception from HRESULT: 0x800706BE)"

Cause 1: OneNote is not open during the conversion.

Solution 1: Open OneNote and keep it open during the conversion.

Cause 2: : Page content bug.

Solution 2: Create a new section, copy pages into it, run the script again. See case.

Error: Convert-OneNotePage : Error while renaming image file name references to 'xxx.png: Illegal characters in path.

Cause: Windows Powershell ISE does not support long paths using the \\?\ prefix, e.g. \\?\C:\path\to.

Solution: Do not use Window Powershell ISE. Use Windows Powershell, or Powershell Core. See requirements.

Credits