sphinx-notionbuilder 2025.10.1

Sphinx extension to build Notion pages.

Notion Builder for Sphinx

Extension for Sphinx which enables publishing documentation to Notion.

Contents

• Notion Builder for Sphinx

  • Installation

  • Supported markup

  • Using Audio

  • Using PDFs

  • Using Colored Text

  • Uploading Documentation to Notion

    • Prerequisites

    • Usage

Installation

sphinx-notionbuilder is compatible with Python 3.11+.

$ pip install sphinx-notionbuilder

Add the following to conf.py to enable the extension:

"""Configuration for Sphinx."""

extensions = ["sphinx_notion"]

For collapsible sections (toggle blocks), also add the sphinx-toolbox collapse extension:

"""Configuration for Sphinx."""

extensions = [
    "sphinx_notion",
    "sphinx_toolbox.collapse",
]

For video support, also add the sphinxcontrib-video extension:

"""Configuration for Sphinx."""

extensions = [
    "sphinxcontrib.video",  # Must be before sphinx_notion
    "sphinx_notion",
]

For strikethrough text support, also add the sphinxnotes-strike extension:

"""Configuration for Sphinx."""

extensions = [
    "sphinxnotes.strike",  # Must be before sphinx_notion
    "sphinx_notion",
]

For audio support, also add the atsphinx-audioplayer extension:

"""Configuration for Sphinx."""

extensions = [
    "atsphinx.audioplayer",
    "sphinx_notion",
]

PDF support is included by default with the sphinx-notionbuilder extension.

Supported markup

The following syntax is supported:

• Headers

• Bulleted lists

• Code blocks

• Table of contents

• Block quotes

• All standard admonitions (note, warning, tip, attention, caution, danger, error, hint, important)

• Collapsible sections (using sphinx-toolbox collapse directive)

• Images (with URLs or local paths)

• Videos (with URLs or local paths)

• Audio (with URLs or local paths)

• PDFs (with URLs or local paths)

• Tables

• Strikethrough text

• Colored text

See a sample document source and the published Notion page.

Using Audio

Audio files can be embedded using the audio directive. Both remote URLs and local file paths are supported:

.. audio:: https://www.example.com/audio.mp3

.. audio:: _static/local-audio.mp3

The audio will be rendered as an audio player in the generated Notion page.

Using PDFs

PDF files can be embedded using the pdf-include directive. Both remote URLs and local file paths are supported.

.. pdf-include:: https://www.example.com/document.pdf

.. pdf-include:: _static/local-document.pdf

The PDF will be rendered as an embedded PDF viewer in the generated Notion page.

Using Colored Text

Colored text can be added using the sphinxcontrib-text-styles extension. First, install the extension:

$ pip install sphinxcontrib-text-styles

Then add it to your conf.py:

"""Configuration for Sphinx."""

extensions = [
    "sphinxcontrib_text_styles",
    "sphinx_notion",
]

You can then use colored text in your reStructuredText documents:

This is :text-red:`red text`, :text-blue:`blue text`, and :text-green:`green text`.

The following colors are supported: red, blue, green, yellow, orange, purple, pink, brown, and gray.

Uploading Documentation to Notion

After building your documentation with the Notion builder, you can upload it to Notion using the included command-line tool.

Prerequisites

1. Create a Notion integration at https://www.notion.so/my-integrations

2. Get your integration token and set it as an environment variable:

$ export NOTION_TOKEN="your_integration_token_here"

Usage

$ notion-upload -f path/to/output.json -p parent_page_id -t "Page Title"

Arguments:

• --file: Path to the JSON file generated by the Notion builder

• --parent-id: The ID of the parent page or database in Notion (must be shared with your integration)

• --parent-type: “page” or “database”

• --title: Title for the new page in Notion

The command will create a new page if one with the given title doesn’t exist, or update the existing page if one with the given title already exists.