You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Extension for Sphinx which enables publishing documentation to Notion.
6
+
Builder for Sphinx which enables publishing documentation to Notion.
7
+
8
+
See a `sample document source`_ and the `published Notion page`_ for an example of what it can do.
7
9
8
10
.. contents::
9
11
@@ -24,31 +26,43 @@ Add the following to ``conf.py`` to enable the extension:
24
26
25
27
extensions = ["sphinx_notion"]
26
28
27
-
For collapsible sections (toggle blocks), also add the `sphinx-toolbox collapse <https://sphinx-toolbox.readthedocs.io/en/stable/extensions/collapse.html>`_ extension:
29
+
``sphinx-notionbuilder`` also works with a variety of Sphinx extensions:
28
30
29
-
.. code-block:: python
31
+
* `sphinx-toolbox collapse`_
32
+
* `sphinx-toolbox rest_example`_
33
+
* `sphinxcontrib-video`_
34
+
* `sphinxnotes-strike`_
35
+
* `atsphinx-audioplayer`_
36
+
* `sphinx-immaterial task_lists`_
37
+
* `sphinx.ext.mathjax`_
38
+
* `sphinx-simplepdf`_
39
+
* `sphinx-iframes`_
40
+
* `sphinxcontrib-text-styles`_
30
41
31
-
"""Configuration for Sphinx."""
32
-
33
-
extensions = [
34
-
"sphinx_notion",
35
-
"sphinx_toolbox.collapse",
36
-
]
42
+
See a `sample document source`_ and the `published Notion page`_ for an example of each of these.
37
43
38
-
For video support, also add the `sphinxcontrib-video <https://sphinxcontrib-video.readthedocs.io>`_ extension:
44
+
To set these up, install the extensions you want to use and add them to your ``conf.py``, before ``sphinx_notion``:
39
45
40
46
.. code-block:: python
41
47
42
48
"""Configuration for Sphinx."""
43
49
44
50
extensions = [
45
-
# ``sphinxcontrib.video`` must be before ``sphinx_notion``
51
+
"atsphinx.audioplayer",
52
+
"sphinx.ext.mathjax",
53
+
"sphinx_iframes",
54
+
"sphinx_immaterial.task_lists",
55
+
"sphinx_simplepdf",
56
+
"sphinx_toolbox.collapse",
57
+
"sphinx_toolbox.rest_example",
46
58
"sphinxcontrib.video",
59
+
"sphinxcontrib_text_styles",
60
+
"sphinxnotes.strike",
47
61
"sphinx_notion",
48
62
]
49
63
50
-
If you are using ``sphinxcontrib.video`` with ``sphinx-iframes``, the warning ``app.add_directive`` will be raised.
51
-
This is because ``sphinxcontrib.video`` and ``sphinx-iframes`` both implement a ``video`` directive.
64
+
If you are using ``sphinxcontrib.video`` with ``sphinx_iframes``, the warning ``app.add_directive`` will be raised.
65
+
This is because ``sphinxcontrib.video`` and ``sphinx_iframes`` both implement a ``video`` directive.
52
66
To suppress this warning, add the following to your ``conf.py``:
53
67
54
68
.. code-block:: python
@@ -57,65 +71,8 @@ To suppress this warning, add the following to your ``conf.py``:
57
71
58
72
suppress_warnings = ["app.add_directive"]
59
73
60
-
For strikethrough text support, also add the `sphinxnotes-strike <https://github.com/sphinx-toolbox/sphinxnotes-strike>`_ extension:
61
-
62
-
.. code-block:: python
63
-
64
-
"""Configuration for Sphinx."""
65
-
66
-
extensions = [
67
-
"sphinxnotes.strike", # Must be before ``sphinx_notion``
68
-
"sphinx_notion",
69
-
]
70
-
71
-
For audio support, also add the `atsphinx-audioplayer <https://github.com/atsphinx/atsphinx-audioplayer>`_ extension:
72
-
73
-
.. code-block:: python
74
-
75
-
"""Configuration for Sphinx."""
76
-
77
-
extensions = [
78
-
"atsphinx.audioplayer",
79
-
"sphinx_notion",
80
-
]
81
-
82
-
For TODO list support, also add the `sphinx-immaterial <https://github.com/jbms/sphinx-immaterial>`_ task lists extension:
83
-
84
-
.. code-block:: python
85
-
86
-
"""Configuration for Sphinx."""
87
-
88
-
extensions = [
89
-
"sphinx_immaterial.task_lists",
90
-
"sphinx_notion",
91
-
]
92
-
93
-
For mathematical equation support, also add the `sphinx.ext.mathjax <https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax>`_ extension:
94
-
95
-
.. code-block:: python
96
-
97
-
"""Configuration for Sphinx."""
98
-
99
-
extensions = [
100
-
"sphinx.ext.mathjax",
101
-
"sphinx_notion",
102
-
]
103
-
104
-
For rest-example blocks support, also add the `sphinx-toolbox <https://sphinx-toolbox.readthedocs.io/>`_ rest-example extension:
105
-
106
-
.. code-block:: python
107
-
108
-
"""Configuration for Sphinx."""
109
-
110
-
extensions = [
111
-
"sphinx_toolbox.rest_example",
112
-
"sphinx_notion",
113
-
]
114
-
115
-
PDF support is included by default with the ``sphinx-notionbuilder`` extension and builds on the `sphinx-simplepdf <https://sphinx-simplepdf.readthedocs.io/>`_ extension.
116
-
117
-
Supported markup
118
-
----------------
74
+
Supported Notion Block Types
75
+
----------------------------
119
76
120
77
The following syntax is supported:
121
78
@@ -125,202 +82,22 @@ The following syntax is supported:
125
82
- Code blocks
126
83
- Table of contents
127
84
- Block quotes
128
-
- All standard admonitions (note, warning, tip, attention, caution, danger, error, hint, important)
129
-
- Collapsible sections (using the ``collapse`` directive from ``sphinx-toolbox``)
130
-
- Rest-example blocks (using the ``rest-example`` directive from ``sphinx-toolbox``)
85
+
- Callouts
86
+
- Collapsible sections (using the ``collapse`` directive from `sphinx-toolbox`_ )
87
+
- Rest-example blocks (using the ``rest-example`` directive from `sphinx-toolbox`_ )
131
88
- Images (with URLs or local paths)
132
89
- Videos (with URLs or local paths)
133
90
- Audio (with URLs or local paths)
134
91
- PDFs (with URLs or local paths)
135
-
- Embed blocks (using the ``iframe`` directive from ``sphinx-iframes``)
92
+
- Embed blocks (using the ``iframe`` directive from `sphinx-iframes`_ )
136
93
- Tables
137
-
- Strikethrough text
138
-
- Colored text and text styles (bold, italic, monospace)
139
-
- Mathematical equations (inline and block-level)
140
-
141
-
See a `sample document source <https://raw.githubusercontent.com/adamtheturtle/sphinx-notionbuilder/refs/heads/main/sample/index.rst>`_ and the `published Notion page <https://www.notion.so/Sphinx-Notionbuilder-Sample-2579ce7b60a48142a556d816c657eb55>`_.
142
-
143
-
Using Audio
144
-
-----------
145
-
146
-
Audio files can be embedded using the ``audio`` directive.
147
-
Both remote URLs and local file paths are supported:
148
-
149
-
.. code-block:: rst
150
-
151
-
.. audio:: https://www.example.com/audio.mp3
152
-
153
-
.. audio:: _static/local-audio.mp3
154
-
155
-
The audio will be rendered as an audio player in the generated Notion page.
156
-
157
-
Using PDFs
158
-
----------
159
-
160
-
PDF files can be embedded using the ``pdf-include`` directive.
161
-
Both remote URLs and local file paths are supported.
The iframes will be rendered as embed blocks in the generated Notion page, allowing you to embed external content like videos, interactive demos, or other web content.
198
-
However, if you are using ``sphinx-iframes`` with ``sphinxcontrib.video``, the warning ``app.add_directive`` will be raised.
199
-
This is because ``sphinx-iframes`` and ``sphinxcontrib.video`` both implement a ``video`` directive.
200
-
To suppress this warning, add the following to your ``conf.py``:
201
-
202
-
.. code-block:: python
203
-
204
-
"""Configuration for Sphinx."""
205
-
206
-
suppress_warnings = ["app.add_directive"]
207
-
208
-
Using Text Styles
209
-
-----------------
210
-
211
-
Text styles can be added using the `sphinxcontrib-text-styles <https://sphinxcontrib-text-styles.readthedocs.io/>`_ extension. First, install the extension:
212
-
213
-
.. code-block:: console
214
-
215
-
$ pip install sphinxcontrib-text-styles
216
-
217
-
Then add it to your ``conf.py``:
218
-
219
-
.. code-block:: python
220
-
221
-
"""Configuration for Sphinx."""
222
-
223
-
extensions = [
224
-
"sphinxcontrib_text_styles",
225
-
"sphinx_notion",
226
-
]
227
-
228
-
You can then use various text styles in your reStructuredText documents:
229
-
230
-
Text Colors
231
-
~~~~~~~~~~~
232
-
233
-
.. code-block:: rst
234
-
235
-
This is :text-red:`red text`, :text-blue:`blue text`, and :text-green:`green text`.
236
-
237
-
The following text colors are supported: red, blue, green, yellow, orange, purple, pink, brown, and gray.
238
-
239
-
Background Colors
240
-
~~~~~~~~~~~~~~~~~
241
-
242
-
.. code-block:: rst
243
-
244
-
This is :bg-red:`red background text`, :bg-blue:`blue background text`, and :bg-green:`green background text`.
245
-
246
-
The following background colors are supported: red, blue, green, yellow, orange, purple, pink, brown, and gray.
247
-
248
-
Additional Text Styles
249
-
~~~~~~~~~~~~~~~~~~~~~~
250
-
251
-
.. code-block:: rst
252
-
253
-
This is :text-bold:`bold text`, :text-italic:`italic text`, :text-mono:`monospace text`, :text-strike:`strikethrough text`, and :text-underline:`underlined text`.
254
-
255
-
The following additional text styles are supported:
256
-
257
-
- ``:text-bold:`text`` - Makes text bold
258
-
- ``:text-italic:`text`` - Makes text italic
259
-
- ``:text-mono:`text`` - Makes text monospace
260
-
- ``:text-strike:`text`` - Makes text strikethrough
261
-
- ``:text-underline:`text`` - Makes text underlined
262
-
263
-
Using TODO Lists
264
-
----------------
265
-
266
-
TODO lists with checkboxes can be created using the ``sphinx-immaterial.task_lists`` extension. Both bulleted and numbered lists support checkboxes:
267
-
268
-
.. code-block:: rst
269
-
270
-
.. task-list::
271
-
272
-
1. [x] Completed task
273
-
2. [ ] Incomplete task
274
-
3. [ ] Another task
275
-
276
-
* [x] Bulleted completed task
277
-
* [ ] Bulleted incomplete task
278
-
279
-
The checkboxes will be rendered as interactive TODO items in the generated Notion page, with completed tasks showing as checked and incomplete tasks as unchecked.
280
-
281
-
Using Mathematical Equations
282
-
-----------------------------
283
-
284
-
Mathematical equations can be embedded using the ``sphinx.ext.mathjax`` extension.
285
-
Both inline and block-level equations are supported:
286
-
287
-
Inline Equations
288
-
~~~~~~~~~~~~~~~~
289
-
290
-
Inline equations can be written using the ``:math:`` role:
291
-
292
-
.. code-block:: rst
293
-
294
-
This is an inline equation :math:`E = mc^2` in your text.
The equations will be rendered as proper mathematical notation in the generated Notion page, with inline equations appearing within the text flow and block equations appearing as separate equation blocks.
319
-
320
-
Using Rest-Example Blocks
321
-
-------------------------
322
-
323
-
Rest-example blocks can be created using the `sphinx_toolbox.rest_example <https://sphinx-toolbox.readthedocs.io/en/stable/extensions/rest_example.html>`_ extension to create example blocks that show both source code and expected output. These are rendered as callout blocks in Notion with nested code blocks:
100
+
All of these can be used in a way which means your documentation can still be rendered to HTML.
324
101
325
102
Unsupported Notion Block Types
326
103
------------------------------
@@ -353,8 +130,8 @@ After building your documentation with the Notion builder, you can upload it to
353
130
Prerequisites
354
131
~~~~~~~~~~~~~
355
132
356
-
1. Create a Notion integration at https://www.notion.so/my-integrations
357
-
2. Get your integration token and set it as an environment variable:
133
+
#. Create a Notion integration at `notion-integrations`_
134
+
#. Get your integration token and set it as an environment variable:
358
135
359
136
.. code-block:: console
360
137
@@ -382,3 +159,18 @@ The command will create a new page if one with the given title doesn't exist, or
0 commit comments