sphinx-notionbuilder 2025.9.11

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

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

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)

• Tables

See a sample document source and the published 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.