Convert IPYNB to ASCIIDOC

Why Convert IPYNB to ASCIIDOC?

Converting Jupyter Notebooks to AsciiDoc format enables you to transform interactive computational documents into professionally structured technical documentation. Notebooks are excellent for exploration and prototyping, but AsciiDoc excels at producing publication-quality output.

AsciiDoc offers richer document semantics than most lightweight markup languages. Features like admonition blocks, cross-references, conditional includes, and bibliography support make it ideal for creating comprehensive technical documentation from notebook content.

The conversion preserves your notebook's narrative flow, converting markdown cells to AsciiDoc markup and code cells to properly formatted source blocks. This allows you to create tutorials, technical reports, and documentation that can be published in multiple formats through the Asciidoctor toolchain.

Key Benefits of Converting IPYNB to ASCIIDOC:

• Publication Quality: Generate professional documents from notebook content
• Rich Semantics: Leverage AsciiDoc's advanced features like admonitions and cross-references
• Multi-Format Output: Render to HTML5, PDF, EPUB3, and DocBook from one source
• Version Control: Plain text format produces meaningful Git diffs
• Code Block Formatting: Notebook code cells become syntax-highlighted source blocks
• Document Composition: Include converted notebooks in larger documentation projects
• Portability: No special software needed to read or edit the text files

Practical Examples

Example 1: ML Experiment Report to AsciiDoc

Input IPYNB file (notebook.ipynb):

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["# Random Forest Classifier Experiment\n",
                  "## Model Configuration\n",
                  "Testing accuracy with different `n_estimators` values."]
    },
    {
      "cell_type": "code",
      "source": ["from sklearn.ensemble import RandomForestClassifier\n",
                  "from sklearn.metrics import accuracy_score\n",
                  "model = RandomForestClassifier(n_estimators=100)\n",
                  "model.fit(X_train, y_train)\n",
                  "pred = model.predict(X_test)\n",
                  "print(f'Accuracy: {accuracy_score(y_test, pred):.4f}')"],
      "outputs": [{"text": "Accuracy: 0.9245"}]
    }
  ]
}

Output ASCIIDOC file (notebook.asciidoc):

= Random Forest Classifier Experiment

== Model Configuration

Testing accuracy with different `n_estimators` values.

[source,python]
----
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score
model = RandomForestClassifier(n_estimators=100)
model.fit(X_train, y_train)
pred = model.predict(X_test)
print(f'Accuracy: {accuracy_score(y_test, pred):.4f}')
----

.Output
----
Accuracy: 0.9245
----

Example 2: Technical Guide to AsciiDoc

Input IPYNB file (analysis.ipynb):

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["## Database Connection Setup\n",
                  "This guide shows how to connect to PostgreSQL.\n",
                  "**Prerequisites:** `psycopg2` library installed."]
    },
    {
      "cell_type": "code",
      "source": ["import psycopg2\n",
                  "conn = psycopg2.connect(\n",
                  "    host='localhost',\n",
                  "    dbname='analytics',\n",
                  "    user='admin'\n",
                  ")\n",
                  "cursor = conn.cursor()\n",
                  "cursor.execute('SELECT count(*) FROM users')\n",
                  "print(cursor.fetchone())"],
      "outputs": [{"text": "(15432,)"}]
    }
  ]
}

Output ASCIIDOC file (analysis.asciidoc):

== Database Connection Setup

This guide shows how to connect to PostgreSQL.

*Prerequisites:* `psycopg2` library installed.

[source,python]
----
import psycopg2
conn = psycopg2.connect(
    host='localhost',
    dbname='analytics',
    user='admin'
)
cursor = conn.cursor()
cursor.execute('SELECT count(*) FROM users')
print(cursor.fetchone())
----

.Output
----
(15432,)
----

Example 3: Research Paper Notebook to AsciiDoc

Input IPYNB file (research.ipynb):

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["# Statistical Analysis of Climate Data\n",
                  "## Methodology\n",
                  "We apply linear regression to 50 years of temperature records."]
    },
    {
      "cell_type": "code",
      "source": ["import scipy.stats as stats\n",
                  "slope, intercept, r, p, se = stats.linregress(years, temps)\n",
                  "print(f'Trend: {slope:.4f} C/year')\n",
                  "print(f'R-squared: {r**2:.4f}')\n",
                  "print(f'P-value: {p:.6f}')"],
      "outputs": [{"text": "Trend: 0.0187 C/year\nR-squared: 0.7834\nP-value: 0.000012"}]
    }
  ]
}

Output ASCIIDOC file (research.asciidoc):

= Statistical Analysis of Climate Data

== Methodology

We apply linear regression to 50 years of temperature records.

[source,python]
----
import scipy.stats as stats
slope, intercept, r, p, se = stats.linregress(years, temps)
print(f'Trend: {slope:.4f} C/year')
print(f'R-squared: {r**2:.4f}')
print(f'P-value: {p:.6f}')
----

.Output
----
Trend: 0.0187 C/year
R-squared: 0.7834
P-value: 0.000012
----

Frequently Asked Questions (FAQ)

Q: What is the difference between ADOC and ASCIIDOC file extensions?

A: Both .adoc and .asciidoc are valid file extensions for AsciiDoc documents. The .adoc extension is a shorter alias commonly used in modern projects, while .asciidoc is the full-length extension. Both are processed identically by Asciidoctor and other AsciiDoc processors.

Q: How are Python code cells represented in AsciiDoc?

A: Python code cells are converted to AsciiDoc source blocks with language annotations. This allows processors like Asciidoctor to apply syntax highlighting when rendering to HTML or PDF, preserving the code readability from the original notebook.

Q: Are cell outputs included in the AsciiDoc conversion?

A: Text-based outputs such as print statements and data tables are included as literal or listing blocks in the AsciiDoc output. Binary outputs like images and charts cannot be directly embedded in AsciiDoc text and would need to be exported separately.

Q: Can I add AsciiDoc-specific features after conversion?

A: Absolutely. After conversion, you can enhance the document with AsciiDoc features such as admonition blocks, cross-references, table of contents, conditional content, include directives, and bibliography entries. This is one of the key advantages of converting to AsciiDoc.

Q: How does the converter handle notebook metadata?

A: Notebook metadata such as the kernel specification and language info is extracted and can be included as document attributes at the top of the AsciiDoc file. This preserves context about the original notebook environment.

Q: Can I convert the AsciiDoc output back to a notebook?

A: Converting back from AsciiDoc to IPYNB is not a standard workflow because AsciiDoc does not maintain cell execution state or kernel information. The conversion to AsciiDoc is best viewed as a one-way transformation for documentation purposes.

Q: Is the AsciiDoc output compatible with Antora documentation sites?

A: Yes. Antora is a multi-repository documentation site generator that uses AsciiDoc as its native content format. Converted notebook files can be placed directly into an Antora component structure for publishing as part of a documentation site.

Q: How are markdown headings in notebooks mapped to AsciiDoc?

A: Markdown headings using # syntax are converted to AsciiDoc heading syntax using = characters. For example, a ## heading in a markdown cell becomes == in AsciiDoc, maintaining the document's hierarchical structure.