Make your documentation awesome
Make the most out of your Sphinx documentation by using the features of the Awesome Theme.
Use headerlink icons
By default, Sphinx shows a
¶ character after section titles and captions
You can change the default with the setting
For example, you can replace the default character with a
You can use SVG icons or plain characters.
If you’re using plain characters with the Awesome Theme,
wrap them in a
This shows the headerlinks only when hovering over the heading,
or when changing the focus with your keyboard.
The Awesome Theme makes sharing links to specific sections in your documentation easier.
Clicking a permalink of a heading, table, or code block copies the URL to the clipboard.
To deactivate this behavior, set the option
Highlight placeholder text in code blocks
To highlight text in code blocks, add the
emphasize-text: PLACEHOLDER option to the
.. code-block:: :emphasize-text: PLACEHOLDER echo "Replace PLACEHOLDER text"
echo "Replace PLACEHOLDER"
Highlight code changes
To highlight changes in code, for example, lines of code that should be added or removed,
the Awesome Theme adds these options to the
emphasize-addedfor highlighting added lines with a green background
emphasize-removedfor highlighting removed lines with a red background
.. code-block:: shell :emphasize-removed: 1 :emphasize-added: 2 echo "Hello World" echo "Hello You"
echo "Hello World"
You can also use the built-in
diff language to get a similar effect:
.. code-block:: diff + echo "Hello You" - echo "Hello World"
+ echo "Hello You" - echo "Hello World"
diff language only highlights the changes.
The rest of the lines render as plain text without syntax highlighting.
If you copy the code, the
- characters are copied as well.
Add as-you-type search with Algolia DocSearch
To get a fast and relevant search-as-you-type experience, you can use Algolia DocSearch as a replacement for Sphinx’ built-in search. It’s free for open source documentation projects and blogs with technical content.