sphinx-notionbuilder 2025.9.25.4

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

  • 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",
]

Supported markup

The following syntax is supported:

• Headers

• Bulleted lists

• Code blocks

• Table of contents

• Block quotes

• Note, warning, and tip admonitions

• 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)

• Tables

• Strikethrough 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.

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:

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

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

• -t, --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.