Documentation.NotebookToMarkdown 2.0.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. To enable it, place the plugin assembly in the plugins folder of a docfx template and reference that template from your build.

1. Restore the package and copy the plugin assembly (and Newtonsoft.Json.dll) into a template:

   _templates/NotebookPlugin/plugins/
     Documentation.NotebookToMarkdown.dll
     Newtonsoft.Json.dll
   

   Use the lib/net8.0 or lib/net10.0 assembly that matches the runtime your docfx tool runs on.

2. Reference the template in docfx.json (alongside default or your own template):

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

3. Run docfx build. Each .ipynb is converted and rendered to an .html page.

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