Metadata-Version: 2.4
Name: sphinx-notionbuilder
Version: 2026.8.11
Summary: Sphinx extension to build Notion pages.
Author-email: Adam Dangoor <adamdangoor@gmail.com>
License-Expression: MIT
Project-URL: Source, https://github.com/adamtheturtle/sphinx-notionbuilder
Keywords: notion,sphinx
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: atsphinx-audioplayer>=0.2.1
Requires-Dist: beartype>=0.21.0
Requires-Dist: beautifulsoup4>=4.13.3
Requires-Dist: click>=8.0.0
Requires-Dist: cloup>=3.0.0
Requires-Dist: docutils>=0.21
Requires-Dist: notion-client<4,>=3.1
Requires-Dist: requests>=2.32.5
Requires-Dist: sphinx<10,>=9
Requires-Dist: sphinx-iframes>=1.1.0
Requires-Dist: sphinx-immaterial>=0.13.7
Requires-Dist: sphinx-simplepdf>=1.6.0
Requires-Dist: sphinx-toolbox>=4.3.0
Requires-Dist: sphinxcontrib-mermaid>=1.0.0
Requires-Dist: sphinxcontrib-video>=0.4.0
Requires-Dist: sphinxnotes-strike>=2.0
Requires-Dist: ultimate-notion<0.11,>=0.10.1
Provides-Extra: dev
Requires-Dist: actionlint-py==1.7.12.24; extra == "dev"
Requires-Dist: anstrip==0.2.2; extra == "dev"
Requires-Dist: check-manifest==0.51; extra == "dev"
Requires-Dist: deptry==0.25.1; extra == "dev"
Requires-Dist: doc8==2.0.0; extra == "dev"
Requires-Dist: doccmd==2026.7.19; extra == "dev"
Requires-Dist: freezegun==1.5.5; extra == "dev"
Requires-Dist: furo==2025.12.19; extra == "dev"
Requires-Dist: interrogate==1.7.0; extra == "dev"
Requires-Dist: mypy[faster-cache]==2.3.0; extra == "dev"
Requires-Dist: mypy-strict-kwargs==2026.7.19.1; extra == "dev"
Requires-Dist: no-defaults==2.1.0; extra == "dev"
Requires-Dist: prek==0.4.12; extra == "dev"
Requires-Dist: pydocstringformatter==1.0.0; extra == "dev"
Requires-Dist: pydocstyle==6.3; extra == "dev"
Requires-Dist: pygments==2.20.0; extra == "dev"
Requires-Dist: pylint[spelling]==4.0.6; extra == "dev"
Requires-Dist: pylint-per-file-ignores==3.2.1; extra == "dev"
Requires-Dist: pyproject-fmt==2.27.0; extra == "dev"
Requires-Dist: pyrefly==1.2.0; extra == "dev"
Requires-Dist: pyright==1.1.411; extra == "dev"
Requires-Dist: pyroma==5.0.1; extra == "dev"
Requires-Dist: pytest==9.1.1; extra == "dev"
Requires-Dist: pytest-beartype-tests==2026.4.26; extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: pytest-regressions==2.11.0; extra == "dev"
Requires-Dist: pyyaml==6.0.3; extra == "dev"
Requires-Dist: ruff==0.16.2; extra == "dev"
Requires-Dist: shellcheck-py==0.11.0.1; extra == "dev"
Requires-Dist: shfmt-py==4.0.0; extra == "dev"
Requires-Dist: sphinx-design>=0.6.0; extra == "dev"
Requires-Dist: sphinx-lint==1.0.2; extra == "dev"
Requires-Dist: sphinx-pyproject==0.3.0; extra == "dev"
Requires-Dist: sphinx-substitution-extensions==2026.8.5; extra == "dev"
Requires-Dist: sphinx-tabs>=3.5.0; extra == "dev"
Requires-Dist: sphinxcontrib-spelling==8.0.2; extra == "dev"
Requires-Dist: sphinxcontrib-text-styles==0.2.1; extra == "dev"
Requires-Dist: strict-kwargs==2026.7.24; extra == "dev"
Requires-Dist: towncrier==25.8.0; extra == "dev"
Requires-Dist: ty==0.0.69; extra == "dev"
Requires-Dist: types-docutils==0.22.3.20260724; extra == "dev"
Requires-Dist: types-requests==2.33.0.20260712; extra == "dev"
Requires-Dist: vale==3.13.0.0; extra == "dev"
Requires-Dist: vulture==2.16; extra == "dev"
Requires-Dist: wiremock-mock==2026.6.22; extra == "dev"
Requires-Dist: yamlfix==1.19.1; extra == "dev"
Requires-Dist: zizmor==1.29.0; extra == "dev"
Provides-Extra: release
Requires-Dist: check-wheel-contents==0.6.3; extra == "release"
Requires-Dist: towncrier==25.8.0; extra == "release"
Provides-Extra: sample
Requires-Dist: sphinx-design>=0.6.0; extra == "sample"
Requires-Dist: sphinx-jinja==2.0.2; extra == "sample"
Requires-Dist: sphinx-tabs>=3.5.0; extra == "sample"
Requires-Dist: sphinxcontrib-text-styles==0.2.1; extra == "sample"
Dynamic: license-file

|Build Status| |PyPI|

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::

Installation
------------

``sphinx-notionbuilder`` is compatible with Python |minimum-python-version|\+.

.. code-block:: console

   $ pip install sphinx-notionbuilder

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

.. code-block:: python

   """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`_
* `sphinx-tabs`_
* `sphinx-design`_
* `sphinxcontrib-text-styles`_
* `sphinxcontrib-mermaid`_

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``:

.. code-block:: python

   """Configuration for Sphinx."""

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

Most of these extensions are installed automatically with ``sphinx-notionbuilder``.
``sphinx-tabs`` and ``sphinx-design`` are not, so to use their directives
(``tabs``/``tab`` and ``tab-set``/``tab-item`` respectively) install them
separately:

.. code-block:: console

   $ pip install sphinx-tabs sphinx-design

Supported Notion Block Types
----------------------------

The following syntax is supported:

- Headers (levels 1-4)
- Bulleted lists
- TODO lists (with checkboxes)
- Code blocks
- Table of contents
- Block quotes
- Callouts
- Collapsible sections (using the ``collapse`` directive from `sphinx-toolbox`_ )
- Tabs (using the ``tabs`` and ``tab`` directives from `sphinx-tabs`_, or the ``tab-set`` and ``tab-item`` directives from `sphinx-design`_ )
- 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)
- Files (with URLs or local paths)
- Embed blocks (using the ``iframe`` directive from `sphinx-iframes`_ )
- Tables
- Dividers (horizontal rules / transitions)
- Strikethrough text (using the ``strike`` role from `sphinxnotes-strike`_ )
- Colored text and text styles (bold, italic, monospace) (using various roles from `sphinxcontrib-text-styles`_ )
- Mermaid diagrams (using the ``mermaid`` directive from `sphinxcontrib-mermaid`_ )
- Mathematical equations (inline and block-level, using the ``math`` role and directive from `sphinx.ext.mathjax`_ )
- Link to page blocks (using the ``notion-link-to-page`` directive)
- Mentions (users, pages, databases, dates) (using the ``notion-mention-user``, ``notion-mention-page``, ``notion-mention-database``, and ``notion-mention-date`` roles)
- Describe blocks (using the ``describe`` directive)
- Definition lists
- Glossary definitions (using the ``glossary`` directive)
- Rubrics (informal headings that do not appear in the table of contents)

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.

Directives
----------

``sphinx-notionbuilder`` provides custom directives for Notion-specific features:

``notion-link-to-page``
~~~~~~~~~~~~~~~~~~~~~~~

Creates a Notion "link to page" block that references another page in your Notion workspace.

**Usage:**

.. code-block:: rst

   .. notion-link-to-page:: PAGE_ID

**Parameters:**

- ``PAGE_ID``: The UUID of the Notion page you want to link to (without hyphens or with hyphens, both formats are accepted)

**Example:**

.. code-block:: rst

   .. notion-link-to-page:: 12345678-1234-1234-1234-123456789abc

This creates a clickable link block in Notion that navigates to the specified page when clicked.

``notion-file``
~~~~~~~~~~~~~~~

Creates a Notion File block that links to an external file by URL, or uploads a local file.

**Usage:**

.. code-block:: rst

   .. notion-file:: FILE_URL_OR_PATH

**Parameters:**

- ``FILE_URL_OR_PATH``: A URL to an external file, or a local file path relative to the source directory

**Options:**

- ``:name:``: (Optional) Display name for the file in Notion
- ``:caption:``: (Optional) Caption text displayed below the file block

**Examples:**

.. code-block:: rst

   .. notion-file:: https://example.com/document.zip

   .. notion-file:: _static/data.csv
      :name: Project Data
      :caption: CSV export of the project data

When not using the Notion builder (e.g. HTML), the directive renders as a link to the file.

Roles
-----

``sphinx-notionbuilder`` provides custom roles for inline Notion-specific features:

``notion-mention-user``
~~~~~~~~~~~~~~~~~~~~~~~

Creates a Notion user mention inline.

**Usage:**

.. code-block:: rst

   :notion-mention-user:`USER_ID`

**Parameters:**

- ``USER_ID``: The UUID of the Notion user you want to mention

**Example:**

.. code-block:: rst

   Hello :notion-mention-user:`12345678-1234-1234-1234-123456789abc` there!


``notion-mention-page``
~~~~~~~~~~~~~~~~~~~~~~~

Creates a Notion page mention inline.

**Usage:**

.. code-block:: rst

   :notion-mention-page:`PAGE_ID`

**Parameters:**

- ``PAGE_ID``: The UUID of the Notion page you want to mention

**Example:**

.. code-block:: rst

   See :notion-mention-page:`87654321-4321-4321-4321-cba987654321` for details.

``notion-mention-database``
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creates a Notion database mention inline.

**Usage:**

.. code-block:: rst

   :notion-mention-database:`DATABASE_ID`

**Parameters:**

- ``DATABASE_ID``: The UUID of the Notion database you want to mention

**Example:**

.. code-block:: rst

   Check the :notion-mention-database:`abcdef12-3456-7890-abcd-ef1234567890` database.

``notion-mention-date``
~~~~~~~~~~~~~~~~~~~~~~~

Creates a Notion date mention inline.

**Usage:**

.. code-block:: rst

   :notion-mention-date:`DATE_STRING`

**Parameters:**

- ``DATE_STRING``: A date string in ISO format (e.g., ``2025-11-09``)

**Example:**

.. code-block:: rst

   The meeting is on :notion-mention-date:`2025-11-09`.

Cross-references
----------------

Sphinx cross-reference roles are not fully supported by the Notion builder because there is no way to determine the URL of the target page in Notion.
Cross-references that resolve to internal links are rendered as plain text and a build warning is emitted.

The affected roles include ``:doc:``, ``:ref:``, ``:term:``, ``:any:``, ``:numref:``, ``:keyword:``, ``:option:``, ``:envvar:``, ``:confval:``, and ``:token:``.

To suppress these warnings, add the following to your ``conf.py``:

.. code-block:: python

   """Configuration for Sphinx."""

   suppress_warnings = ["ref.notion"]

Unsupported Notion Block Types
------------------------------

- Bookmark
- Breadcrumb
- Child database
- Child page
- Column and column list
- Link preview
- Synced block
- Template
- Heading with ``is_toggleable`` set to ``True``

Uploading Documentation to Notion
----------------------------------

Build documentation with the ``notion`` builder.
For eaxmple:

.. code-block:: console

   $ 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
~~~~~~~~~~~~~

#. Create a Notion integration at `notion-integrations`_

The integration token must have the following "Capabilities" set within the "Configuration" tab:

- **Content Capabilities**: Insert content, Update content, Read content
- **Comment Capabilities**: Read comments (required for checking if blocks have discussion threads for the ``--cancel-on-discussion`` option)
- **User Capabilities**: Read user information without email addresses (for bot identification)

In the "Access" tab, choose the pages and databases your integration can access.

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

.. code-block:: console

   $ export NOTION_TOKEN="your_integration_token_here"

Usage
~~~~~


.. code-block:: console

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

Or with a database parent:

.. code-block:: console

   $ notion-upload --file path/to/output.json --parent-database-id parent_database_id --title "Page Title"

Or update a known page directly, without specifying its parent:

.. code-block:: console

   $ notion-upload --file path/to/output.json --page-id page_id --title "Page Title"

Arguments:

- ``--file``: Path to the JSON file generated by the Notion builder
- ``--parent-page-id``: The ID of the parent page in Notion (must be shared with your integration) - required without ``--page-id`` and mutually exclusive with ``--parent-database-id``
- ``--parent-database-id``: The ID of the parent database in Notion (must be shared with your integration) - required without ``--page-id`` and mutually exclusive with ``--parent-page-id``
- ``--title``: Title for the new page in Notion
- ``--page-id``: (Optional) ID of an existing page to update; the page is renamed to the given title
- ``--icon``: (Optional) Icon for the page (emoji)
- ``--cover-path``: (Optional) Path to a cover image file for the page
- ``--strategy``: (Optional) Block upload strategy, ``diff`` (the default) or ``replace``

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.

With ``--page-id``, the page is looked up by ID instead of by title, and the command fails if no page with that ID exists.
This avoids a silent fork where renaming a page (in Notion or in your configuration) causes a new page to be created alongside the old one.

Upload Strategies
~~~~~~~~~~~~~~~~~

The default ``diff`` strategy keeps matching blocks at the beginning and end of the page and only replaces the changed middle.
It minimizes API calls and preserves the IDs and discussion threads of unchanged blocks, but its synchronization algorithm is more involved.

The ``replace`` strategy uploads the complete new document at the bottom of the page and only then deletes every previously existing block.
Appending first means an append failure leaves the old document intact.
This strategy is simpler, but it uploads every block, briefly duplicates the document during synchronization, and replaces all old block IDs and their discussions.
Consequently, ``--cancel-on-discussion`` treats every existing block as deletable when ``replace`` is selected.

Use ``diff`` for routine publishing where preserving discussions and minimizing API calls matter.
Use ``replace`` when append-before-delete failure safety and straightforward replacement matter more than retaining old block IDs.

Automatic Publishing Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Instead of using the command-line tool, you can configure automatic publishing to Notion in your ``conf.py``.
When enabled, documentation will be uploaded to Notion automatically after a successful build with the ``notion`` builder.
Every document reachable from the root document through a ``toctree`` is published as a child of its corresponding Notion page.
The root uses ``notion_page_title`` and the other pages use their Sphinx document titles.
Existing child pages are matched by title and kept in the same hierarchy.

Add the following configuration options to your ``conf.py``:

.. code-block:: python

   """Configuration for Sphinx."""

   # Enable automatic publishing to Notion
   notion_publish = True

   # Required without notion_page_id: Parent page or database ID
   notion_parent_page_id = "your-page-id-here"
   # OR
   notion_parent_database_id = "your-database-id-here"

   # Required: Title for the Notion page
   notion_page_title = "My Documentation"

   # Optional alternative to a parent: ID of an existing page to update
   notion_page_id = "your-page-id-here"

   # Optional: Icon emoji for the page
   notion_page_icon = "📚"

   # Optional: Cover image URL
   notion_page_cover_url = "https://example.com/cover.jpg"

   # Optional: Cancel upload if blocks to be deleted have discussion threads
   notion_cancel_on_discussion = True

   # Optional: Use "diff" (default) or append-then-delete "replace"
   notion_upload_strategy = "diff"

**Configuration Options:**

``notion_publish``
   Enable automatic publishing to Notion after the build completes.
   When set to ``True``, the documentation will be uploaded to Notion automatically after a successful build with the ``notion`` builder.
   Default: ``False``

``notion_parent_page_id``
   The ID of the parent Notion page under which the documentation will be published.
   The page must be shared with your Notion integration.
   This option is mutually exclusive with ``notion_parent_database_id``.
   A parent location is required only when ``notion_page_id`` is not set.
   Default: ``None``

``notion_parent_database_id``
   The ID of the parent Notion database under which the documentation will be published.
   The database must be shared with your Notion integration.
   This option is mutually exclusive with ``notion_parent_page_id``.
   A parent location is required only when ``notion_page_id`` is not set.
   Default: ``None``

``notion_page_title``
   The title for the Notion page.
   This is required when ``notion_publish`` is ``True``.
   If a page with this title already exists under the parent, it will be updated.
   Otherwise, a new page will be created.
   Default: ``None``

``notion_page_id``
   The ID of an existing Notion page to update.
   When set, the page is looked up by ID instead of by title, and is renamed to ``notion_page_title``.
   No parent page or database ID is required in this mode.
   Publishing fails with an error if no page with this ID exists.
   Default: ``None``

``notion_page_icon``
   An optional emoji icon for the Notion page (e.g., ``"📚"``).
   Default: ``None``

``notion_page_cover_url``
   An optional URL for a cover image for the Notion page.
   Default: ``None``

``notion_cancel_on_discussion``
   When set to ``True``, the upload will be cancelled with an error if any blocks that would be deleted have discussion threads attached to them.
   This helps prevent accidentally losing discussion content.
   Default: ``False``

``notion_upload_strategy``
   Selects the block synchronization strategy: ``"diff"`` preserves matching block IDs and discussions while uploading only changes, and ``"replace"`` appends the complete new document before deleting all old blocks.
   With ``"replace"``, all existing blocks are considered deletable by ``notion_cancel_on_discussion``.
   Default: ``"diff"``

Publishing the Sample Document Locally
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A convenience script is provided to build and publish the sample documentation to a test Notion page.

#. Create a ``.env`` file in the repository root with your integration token:

   .. code-block:: shell

      export NOTION_TOKEN=your_integration_token_here

   This file is gitignored and will not be committed.

#. Run the script:

   .. code-block:: console

      $ ./publish-sample.sh

The Notion object IDs that the sample links to and mentions (a page, a user and a database) are read from the committed ``sample.env`` file rather than being hardcoded in the documentation, so the sample can be uploaded to any workspace.

Targeting Your Own Workspace
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The committed ``sample.env`` points at the project's own demo workspace. To regenerate it for a workspace of your own, run the bootstrap script. It creates the linked page and database under a parent page shared with your integration, picks a user to mention, and writes the IDs to ``sample.env``:

.. code-block:: console

   $ export NOTION_TOKEN="your_integration_token_here"
   $ uv run --all-extras python bootstrap-sample-env.py --parent-page-id parent_page_id

.. |Build Status| image:: https://github.com/adamtheturtle/sphinx-notionbuilder/actions/workflows/ci.yml/badge.svg?branch=main
   :target: https://github.com/adamtheturtle/sphinx-notionbuilder/actions
.. |PyPI| image:: https://badge.fury.io/py/Sphinx-Notion-Builder.svg
   :target: https://badge.fury.io/py/Sphinx-Notion-Builder
.. |minimum-python-version| replace:: 3.11

.. _atsphinx-audioplayer: https://github.com/atsphinx/atsphinx-audioplayer
.. _notion-integrations: https://www.notion.so/my-integrations
.. _published Notion page: https://www.notion.so/Sphinx-Notionbuilder-Sample-2579ce7b60a48142a556d816c657eb55
.. _sample document source: https://raw.githubusercontent.com/adamtheturtle/sphinx-notionbuilder/refs/heads/main/sample/index.rst
.. _sphinx-design: https://sphinx-design.readthedocs.io/
.. _sphinx-iframes: https://pypi.org/project/sphinx-iframes/
.. _sphinx-immaterial task_lists: https://github.com/jbms/sphinx-immaterial
.. _sphinx-simplepdf: https://sphinx-simplepdf.readthedocs.io/
.. _sphinx-tabs: https://sphinx-tabs.readthedocs.io/
.. _sphinx-toolbox collapse: https://sphinx-toolbox.readthedocs.io/en/stable/extensions/collapse.html
.. _sphinx-toolbox rest_example: https://sphinx-toolbox.readthedocs.io/en/stable/extensions/rest_example.html
.. _sphinx-toolbox: https://sphinx-toolbox.readthedocs.io/en/stable/extensions/
.. _sphinx.ext.mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax
.. _sphinxcontrib-mermaid: https://github.com/mgaitan/sphinxcontrib-mermaid
.. _sphinxcontrib-text-styles: https://sphinxcontrib-text-styles.readthedocs.io/
.. _sphinxcontrib-video: https://sphinxcontrib-video.readthedocs.io
.. _sphinxnotes-strike: https://github.com/sphinx-toolbox/sphinxnotes-strike
