Documentation.NotebookToMarkdown 2.1.0

Documentation.NotebookToMarkdown

A .NET docfx plugin — and reusable library — that converts Jupyter Notebook (.ipynb) files into rendered documentation.

Use it as a docfx plugin to publish notebooks as ordinary documentation pages, or use the underlying NotebookConverter directly in any pipeline. The only runtime dependency of the converter is Newtonsoft.Json; the docfx plugin contract (Docfx.Plugins) is provided by the docfx host at runtime.

What it does

• Markdown cells are emitted verbatim.
• Code cells are wrapped in fenced code blocks tagged with the notebook's language (from metadata.language_info.name).
• Execution outputs are rendered as HTML:
  • execute_result (text/plain) → <pre class="jupyter-execute-result"><code>…</code></pre>
  • display_data images (image/png, image/gif, image/jpeg) → inline <img> data URIs
• Cell attachments (![alt](attachment:name)) are inlined as base64 data: URIs.
• Raw cells are skipped (matching nbconvert).

If the input cannot be parsed, or is missing required notebook structure, the original input is returned unchanged so callers can fall back gracefully.

Installation

dotnet add package Documentation.NotebookToMarkdown

Target frameworks: net8.0 and net10.0 (current LTS releases).

Use as a docfx plugin

The package ships a docfx IDocumentProcessor (JupyterDocumentProcessor) that claims .ipynb files and routes them through docfx's Markdown pipeline. It also ships a small docfx template (template/) that renders a "Launch Notebook" button on every page produced from a notebook.

A docfx template that contains a plugins/ folder loads both the processor and the button from a single template reference. Assemble one template folder like this:

NotebookTemplate/
  plugins/
    Documentation.NotebookToMarkdown.dll   # from lib/net8.0 or lib/net10.0
    Newtonsoft.Json.dll
  partials/
    affix.tmpl.partial                      # from the package's template/ folder
  token.json                                # from the package's template/ folder

1. Copy the plugin assembly (and Newtonsoft.Json.dll) into NotebookTemplate/plugins/. Use the lib/net8.0 or lib/net10.0 assembly that matches the runtime your docfx tool runs on. The docfx host provides Docfx.* and System.Composition.*, so do not copy those.

2. Copy the package's template/partials/affix.tmpl.partial and template/token.json into NotebookTemplate/ (as shown above) so the button renders.

3. Reference the template in docfx.json (after default so the button partial overrides the default affix):

   {
     "build": {
       "content": [ { "files": ["**/*.ipynb"] } ],
       "dest": "_site",
       "template": [ "default", "NotebookTemplate" ]
     }
   }
   

4. Run docfx build. Each .ipynb is converted and rendered to an .html page, and the build step sets a fromIpynb flag so the bundled template shows the "Launch Notebook" link on those pages.

Use the converter directly

using Documentation.NotebookToMarkdown;

string notebookJson = File.ReadAllText("Hello.ipynb");

var converter = new NotebookConverter();
string markdown = converter.ConvertToMarkdown(notebookJson);

Capturing warnings

Non-fatal issues (for example, a malformed cell) are reported through an optional callback:

var converter = new NotebookConverter(warning => Console.Error.WriteLine(warning));
string markdown = converter.ConvertToMarkdown(notebookJson);

Building and testing

dotnet build
dotnet test

License

MIT