| Name | sphinx-notionbuilder JSON |
| Version |
2025.10.24.1
JSON |
| download |
| home_page | None |
| Summary | Sphinx extension to build Notion pages. |
| upload_time | 2025-10-24 06:52:48 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
notion
sphinx
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
|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`_
* `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``:
.. code-block:: python
"""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",
]
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:
.. 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`_
#. 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"
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) - mutually exclusive with ``--parent-database-id``
- ``--parent-database-id``: The ID of the parent database in Notion (must be shared with your integration) - mutually exclusive with ``--parent-page-id``
- ``--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.
.. |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-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-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-text-styles: https://sphinxcontrib-text-styles.readthedocs.io/
.. _sphinxcontrib-video: https://sphinxcontrib-video.readthedocs.io
.. _sphinxnotes-strike: https://github.com/sphinx-toolbox/sphinxnotes-strike
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-notionbuilder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "notion, sphinx",
"author": null,
"author_email": "Adam Dangoor <adamdangoor@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/92/cd/23839d960086bb07bdb1c60f9f42bbc4c9723456f52d7b38e0c9631de25e/sphinx_notionbuilder-2025.10.24.1.tar.gz",
"platform": null,
"description": "|Build Status| |PyPI|\n\nNotion Builder for Sphinx\n=========================\n\nBuilder for Sphinx which enables publishing documentation to Notion.\n\nSee a `sample document source`_ and the `published Notion page`_ for an example of what it can do.\n\n.. contents::\n\nInstallation\n------------\n\n``sphinx-notionbuilder`` is compatible with Python |minimum-python-version|\\+.\n\n.. code-block:: console\n\n $ pip install sphinx-notionbuilder\n\nAdd the following to ``conf.py`` to enable the extension:\n\n.. code-block:: python\n\n \"\"\"Configuration for Sphinx.\"\"\"\n\n extensions = [\"sphinx_notion\"]\n\n``sphinx-notionbuilder`` also works with a variety of Sphinx extensions:\n\n* `sphinx-toolbox collapse`_\n* `sphinx-toolbox rest_example`_\n* `sphinxcontrib-video`_\n* `sphinxnotes-strike`_\n* `atsphinx-audioplayer`_\n* `sphinx-immaterial task_lists`_\n* `sphinx.ext.mathjax`_\n* `sphinx-simplepdf`_\n* `sphinx-iframes`_\n* `sphinxcontrib-text-styles`_\n\nSee a `sample document source`_ and the `published Notion page`_ for an example of each of these.\n\nTo set these up, install the extensions you want to use and add them to your ``conf.py``, before ``sphinx_notion``:\n\n.. code-block:: python\n\n \"\"\"Configuration for Sphinx.\"\"\"\n\n extensions = [\n \"atsphinx.audioplayer\",\n \"sphinx.ext.mathjax\",\n \"sphinx_iframes\",\n \"sphinx_immaterial.task_lists\",\n \"sphinx_simplepdf\",\n \"sphinx_toolbox.collapse\",\n \"sphinx_toolbox.rest_example\",\n \"sphinxcontrib.video\",\n \"sphinxcontrib_text_styles\",\n \"sphinxnotes.strike\",\n \"sphinx_notion\",\n ]\n\nSupported Notion Block Types\n----------------------------\n\nThe following syntax is supported:\n\n- Headers\n- Bulleted lists\n- TODO lists (with checkboxes)\n- Code blocks\n- Table of contents\n- Block quotes\n- Callouts\n- Collapsible sections (using the ``collapse`` directive from `sphinx-toolbox`_ )\n- Rest-example blocks (using the ``rest-example`` directive from `sphinx-toolbox`_ )\n- Images (with URLs or local paths)\n- Videos (with URLs or local paths)\n- Audio (with URLs or local paths)\n- PDFs (with URLs or local paths)\n- Embed blocks (using the ``iframe`` directive from `sphinx-iframes`_ )\n- Tables\n- Strikethrough text (using the ``strike`` role from `sphinxnotes-strike`_ )\n- Colored text and text styles (bold, italic, monospace) (using various roles from `sphinxcontrib-text-styles`_ )\n- Mathematical equations (inline and block-level, using the ``math`` role and directive from `sphinx.ext.mathjax`_ )\n\nSee a `sample document source`_ and the `published Notion page`_.\n\nAll of these can be used in a way which means your documentation can still be rendered to HTML.\n\nUnsupported Notion Block Types\n------------------------------\n\n- Bookmark\n- Breadcrumb\n- Child database\n- Child page\n- Column and column list\n- Divider\n- File\n- Link preview\n- Mention\n- Synced block\n- Template\n- Heading with ``is_toggleable`` set to ``True``\n\nUploading Documentation to Notion\n----------------------------------\n\nBuild documentation with the ``notion`` builder.\nFor eaxmple:\n\n.. code-block:: console\n\n $ sphinx-build -W -b notion source build/notion\n\nAfter building your documentation with the Notion builder, you can upload it to Notion using the included command-line tool.\n\nPrerequisites\n~~~~~~~~~~~~~\n\n#. Create a Notion integration at `notion-integrations`_\n#. Get your integration token and set it as an environment variable:\n\n.. code-block:: console\n\n $ export NOTION_TOKEN=\"your_integration_token_here\"\n\nUsage\n~~~~~\n\n\n.. code-block:: console\n\n # The JSON file will be in the build directory, e.g. ./build/notion/index.json\n $ notion-upload --file path/to/output.json --parent-page-id parent_page_id --title \"Page Title\"\n\nOr with a database parent:\n\n.. code-block:: console\n\n $ notion-upload --file path/to/output.json --parent-database-id parent_database_id --title \"Page Title\"\n\nArguments:\n\n- ``--file``: Path to the JSON file generated by the Notion builder\n- ``--parent-page-id``: The ID of the parent page in Notion (must be shared with your integration) - mutually exclusive with ``--parent-database-id``\n- ``--parent-database-id``: The ID of the parent database in Notion (must be shared with your integration) - mutually exclusive with ``--parent-page-id``\n- ``--title``: Title for the new page in Notion\n\nThe 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.\n\n.. |Build Status| image:: https://github.com/adamtheturtle/sphinx-notionbuilder/actions/workflows/ci.yml/badge.svg?branch=main\n :target: https://github.com/adamtheturtle/sphinx-notionbuilder/actions\n.. |PyPI| image:: https://badge.fury.io/py/Sphinx-Notion-Builder.svg\n :target: https://badge.fury.io/py/Sphinx-Notion-Builder\n.. |minimum-python-version| replace:: 3.11\n\n.. _atsphinx-audioplayer: https://github.com/atsphinx/atsphinx-audioplayer\n.. _notion-integrations: https://www.notion.so/my-integrations\n.. _published Notion page: https://www.notion.so/Sphinx-Notionbuilder-Sample-2579ce7b60a48142a556d816c657eb55\n.. _sample document source: https://raw.githubusercontent.com/adamtheturtle/sphinx-notionbuilder/refs/heads/main/sample/index.rst\n.. _sphinx-iframes: https://pypi.org/project/sphinx-iframes/\n.. _sphinx-immaterial task_lists: https://github.com/jbms/sphinx-immaterial\n.. _sphinx-simplepdf: https://sphinx-simplepdf.readthedocs.io/\n.. _sphinx-toolbox collapse: https://sphinx-toolbox.readthedocs.io/en/stable/extensions/collapse.html\n.. _sphinx-toolbox rest_example: https://sphinx-toolbox.readthedocs.io/en/stable/extensions/rest_example.html\n.. _sphinx-toolbox: https://sphinx-toolbox.readthedocs.io/en/stable/extensions/\n.. _sphinx.ext.mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax\n.. _sphinxcontrib-text-styles: https://sphinxcontrib-text-styles.readthedocs.io/\n.. _sphinxcontrib-video: https://sphinxcontrib-video.readthedocs.io\n.. _sphinxnotes-strike: https://github.com/sphinx-toolbox/sphinxnotes-strike\n",
"bugtrack_url": null,
"license": null,
"summary": "Sphinx extension to build Notion pages.",
"version": "2025.10.24.1",
"project_urls": {
"Source": "https://github.com/adamtheturtle/sphinx-notionbuilder"
},
"split_keywords": [
"notion",
" sphinx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2f7a69b277b8c2350ee1eee28635f09d952be52afaf48cfb813db248d247a2da",
"md5": "a1f424c19513897db322b4ffc24f7fe7",
"sha256": "0bd0268c73976dfa8bcc192abfa3ef16d98274e0e12b01f16c244ffd9f66e135"
},
"downloads": -1,
"filename": "sphinx_notionbuilder-2025.10.24.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1f424c19513897db322b4ffc24f7fe7",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.12",
"size": 17927,
"upload_time": "2025-10-24T06:52:47",
"upload_time_iso_8601": "2025-10-24T06:52:47.010180Z",
"url": "https://files.pythonhosted.org/packages/2f/7a/69b277b8c2350ee1eee28635f09d952be52afaf48cfb813db248d247a2da/sphinx_notionbuilder-2025.10.24.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "92cd23839d960086bb07bdb1c60f9f42bbc4c9723456f52d7b38e0c9631de25e",
"md5": "75cfccf1544decca5d0e56b6f00f6858",
"sha256": "14393d97d29f210b2cc3b77cd70b211bcbc5eb49e280ee94ca6d330311ad2f22"
},
"downloads": -1,
"filename": "sphinx_notionbuilder-2025.10.24.1.tar.gz",
"has_sig": false,
"md5_digest": "75cfccf1544decca5d0e56b6f00f6858",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 48017,
"upload_time": "2025-10-24T06:52:48",
"upload_time_iso_8601": "2025-10-24T06:52:48.487489Z",
"url": "https://files.pythonhosted.org/packages/92/cd/23839d960086bb07bdb1c60f9f42bbc4c9723456f52d7b38e0c9631de25e/sphinx_notionbuilder-2025.10.24.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 06:52:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adamtheturtle",
"github_project": "sphinx-notionbuilder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-notionbuilder"
}
