sphinx-notionbuilder 2025.10.7

Sphinx extension to build Notion pages.

Notion Builder for Sphinx

Builder for Sphinx which enables publishing documentation to Notion.

See a sample document source and the published Notion page for an example of what it can do.

Contents

• Notion Builder for Sphinx

  • Installation

  • Supported Notion Block Types

  • Unsupported Notion Block Types

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

sphinx-notionbuilder also works with a variety of Sphinx extensions:

• sphinx-toolbox collapse

• sphinx-toolbox rest_example

• sphinxcontrib-video

• sphinxnotes-strike

• atsphinx-audioplayer

• sphinx-immaterial task_lists

• sphinx.ext.mathjax

• sphinx-simplepdf

• sphinx-iframes

• sphinxcontrib-text-styles

See a sample document source and the published Notion page for an example of each of these.

To set these up, install the extensions you want to use and add them to your conf.py, before sphinx_notion:

"""Configuration for Sphinx."""

extensions = [
    "atsphinx.audioplayer",
    "sphinx.ext.mathjax",
    "sphinx_iframes",
    "sphinx_immaterial.task_lists",
    "sphinx_simplepdf",
    "sphinx_toolbox.collapse",
    "sphinx_toolbox.rest_example",
    "sphinxcontrib.video",
    "sphinxcontrib_text_styles",
    "sphinxnotes.strike",
    "sphinx_notion",
]

If you are using sphinxcontrib.video with sphinx_iframes, the warning app.add_directive will be raised. This is because sphinxcontrib.video and sphinx_iframes both implement a video directive. To suppress this warning, add the following to your conf.py:

"""Configuration for Sphinx."""

suppress_warnings = ["app.add_directive"]

Supported Notion Block Types

The following syntax is supported:

• Headers

• Bulleted lists

• TODO lists (with checkboxes)

• Code blocks

• Table of contents

• Block quotes

• Callouts

• Collapsible sections (using the collapse directive from sphinx-toolbox )

• Rest-example blocks (using the rest-example directive from sphinx-toolbox )

• Images (with URLs or local paths)

• Videos (with URLs or local paths)

• Audio (with URLs or local paths)

• PDFs (with URLs or local paths)

• Embed blocks (using the iframe directive from sphinx-iframes )

• Tables

• Strikethrough text (using the strike role from sphinxnotes-strike )

• Colored text and text styles (bold, italic, monospace) (using various roles from sphinxcontrib-text-styles )

• Mathematical equations (inline and block-level, using the math role and directive from sphinx.ext.mathjax )

See a sample document source and the published Notion page.

All of these can be used in a way which means your documentation can still be rendered to HTML.

Unsupported Notion Block Types

• Bookmark

• Breadcrumb

• Child database

• Child page

• Column and column list

• Divider

• File

• Link preview

• Mention

• Synced block

• Template

• Heading with is_toggleable set to True

Uploading Documentation to Notion

Build documentation with the notion builder. For eaxmple:

$ sphinx-build -W -b notion source build/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 notion-integrations

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

$ export NOTION_TOKEN="your_integration_token_here"

Usage

# The JSON file will be in the build directory, e.g. ./build/notion/index.json
$ notion-upload --file path/to/output.json --parent-id parent_page_id --parent-type page --title "Page Title" --sha-mapping notion-sha-mapping.json

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.