Documentation.NotebookToMarkdown 2.2.1

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 is a self-contained docfx plugin payload. It ships a docfx IDocumentProcessor (JupyterDocumentProcessor) that claims .ipynb files and routes them through docfx's Markdown pipeline, and a small docfx template (template/) that renders a "Launch Notebook" button on every page produced from a notebook.

Because everything is embedded in the package, no project or dotnet restore is required - just unzip the .nupkg (it is a plain zip) and copy two folders into a docfx template:

• plugins/<tfm>/ - the plugin assembly and its runtime dependency Newtonsoft.Json.dll, already bundled together. Pick net8.0 or net10.0 to match the runtime your docfx tool runs on. The docfx host provides Docfx.* and System.Composition.*, so those are intentionally not included.
• template/ - the partials/affix.tmpl.partial and token.json that render the button.

NotebookTemplate/
  plugins/
    Documentation.NotebookToMarkdown.dll   # from the package's plugins/<tfm>/ folder
    Newtonsoft.Json.dll                     # bundled in the same folder
  partials/
    affix.tmpl.partial                      # from the package's template/ folder
  token.json                                # from the package's template/ folder

A minimal, project-free assembly (e.g. in a build script or Dockerfile) looks like:

# download + unzip the package, then copy the self-contained payload into a docfx template
unzip Documentation.NotebookToMarkdown.<version>.nupkg -d pkg
mkdir -p NotebookTemplate
cp -r pkg/plugins/net10.0   NotebookTemplate/plugins
cp -r pkg/template/partials NotebookTemplate/partials
cp    pkg/template/token.json NotebookTemplate/token.json

Then 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" ]
  }
}

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