Convert IPYNB to ADOC

Why Convert IPYNB to ADOC?

Converting Jupyter Notebooks to AsciiDoc transforms interactive computational documents into professional technical documentation. Notebooks contain valuable code examples, explanations, and analysis results that are ideal for inclusion in technical publications and documentation sites.

AsciiDoc provides a structured, version-control friendly format that captures the narrative and code content of your notebooks. Unlike the JSON-based IPYNB format, AsciiDoc files produce clean, readable diffs in Git, making collaboration on documentation projects significantly easier.

Once converted to AsciiDoc, your notebook content can be processed by Asciidoctor into multiple output formats including HTML, PDF, EPUB, and DocBook. This makes it easy to publish tutorials, research findings, and data analysis reports in professional formats suitable for distribution.

Key Benefits of Converting IPYNB to ADOC:

• Documentation Quality: Transform notebooks into polished technical documentation
• Version Control: Track changes with meaningful diffs in Git repositories
• Multi-Format Publishing: Generate HTML, PDF, and EPUB from a single AsciiDoc source
• Code Preservation: Code cells become properly formatted AsciiDoc source blocks
• Plain Text Editing: Edit content in any text editor without specialized software
• Modular Includes: Use AsciiDoc include directives to compose larger documents
• Cross-References: Add navigation links, footnotes, and table of contents

Practical Examples

Example 1: Data Analysis Report to AsciiDoc

Input IPYNB file (notebook.ipynb):

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["# Sales Data Analysis Q4 2025\n",
                  "## Overview\n",
                  "This report examines quarterly sales trends."]
    },
    {
      "cell_type": "code",
      "source": ["import pandas as pd\n",
                  "df = pd.read_csv('sales_q4.csv')\n",
                  "print(df.groupby('region')['revenue'].sum())"],
      "outputs": [{"text": "region\nEast     125000\nWest     98000\nNorth    87000"}]
    }
  ]
}

Output ADOC file (notebook.adoc):

= Sales Data Analysis Q4 2025

== Overview

This report examines quarterly sales trends.

[source,python]
----
import pandas as pd
df = pd.read_csv('sales_q4.csv')
print(df.groupby('region')['revenue'].sum())
----

.Output
----
region
East     125000
West     98000
North    87000
----

Example 2: API Documentation to AsciiDoc

Input IPYNB file (analysis.ipynb):

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["## Authentication Endpoint\n",
                  "The `/api/auth` endpoint accepts POST requests.\n",
                  "**Required headers:** `Content-Type: application/json`"]
    },
    {
      "cell_type": "code",
      "source": ["import requests\n",
                  "response = requests.post(\n",
                  "    'https://api.example.com/auth',\n",
                  "    json={'username': 'admin', 'password': 'secret'}\n",
                  ")\n",
                  "print(response.status_code)"],
      "outputs": [{"text": "200"}]
    }
  ]
}

Output ADOC file (analysis.adoc):

== Authentication Endpoint

The `/api/auth` endpoint accepts POST requests.

*Required headers:* `Content-Type: application/json`

[source,python]
----
import requests
response = requests.post(
    'https://api.example.com/auth',
    json={'username': 'admin', 'password': 'secret'}
)
print(response.status_code)
----

.Output
----
200
----

Example 3: Tutorial Notebook to AsciiDoc

Input IPYNB file (research.ipynb):

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["# Getting Started with NumPy\n",
                  "NumPy is the fundamental package for numerical computing.\n",
                  "### Creating Arrays\n",
                  "Use `np.array()` to create arrays from lists."]
    },
    {
      "cell_type": "code",
      "source": ["import numpy as np\n",
                  "arr = np.array([1, 2, 3, 4, 5])\n",
                  "print('Mean:', arr.mean())\n",
                  "print('Std:', arr.std())"],
      "outputs": [{"text": "Mean: 3.0\nStd: 1.4142135623730951"}]
    }
  ]
}

Output ADOC file (research.adoc):

= Getting Started with NumPy

NumPy is the fundamental package for numerical computing.

=== Creating Arrays

Use `np.array()` to create arrays from lists.

[source,python]
----
import numpy as np
arr = np.array([1, 2, 3, 4, 5])
print('Mean:', arr.mean())
print('Std:', arr.std())
----

.Output
----
Mean: 3.0
Std: 1.4142135623730951
----

Frequently Asked Questions (FAQ)

Q: How are Jupyter code cells converted to AsciiDoc?

A: Code cells are converted into AsciiDoc source code blocks with appropriate language syntax highlighting. For example, Python code cells become delimited source blocks with [source,python] attributes, preserving the original code formatting.

Q: Are notebook markdown cells preserved in the AsciiDoc output?

A: Yes. Markdown cells are converted to equivalent AsciiDoc markup. Headings, bold/italic text, links, lists, and other formatting elements are translated to their AsciiDoc counterparts, maintaining the document structure.

Q: What happens to cell outputs and visualizations?

A: Text-based cell outputs are included in the AsciiDoc file as literal blocks. Image outputs such as matplotlib charts are not embedded directly since AsciiDoc is a text format. You may need to export images separately and reference them using AsciiDoc image macros.

Q: Can I convert notebooks with multiple programming languages?

A: Yes. The converter processes all code cells regardless of the kernel language. Whether your notebook uses Python, R, Julia, or another language, the code content is extracted and placed into properly formatted AsciiDoc source blocks.

Q: Is the cell execution order preserved?

A: Yes. Cells are converted in the order they appear in the notebook file, preserving the document flow. The sequential structure of markdown explanations followed by code cells is maintained in the AsciiDoc output.

Q: Can I use the converted file with Asciidoctor directly?

A: Yes. The output is valid AsciiDoc that can be processed immediately by Asciidoctor to generate HTML, PDF, or other formats. You can also include the file in larger documentation projects using the include::[] directive.

Q: How are LaTeX math equations in notebooks handled?

A: LaTeX equations embedded in markdown cells are preserved as literal text in the AsciiDoc output. AsciiDoc supports math rendering through extensions like asciidoctor-mathematical, so the equations can be rendered in the final output.

Q: What is the maximum notebook file size supported?

A: Our converter handles notebooks of typical sizes used in data science workflows. Very large notebooks with extensive embedded output data (such as large base64-encoded images) may take longer to process. For best results, clear cell outputs before conversion if you only need the code and markdown content.