Configuration¶
html_short_title
¶
If you have a really long project name, you may prefer something shorter to
appear in the navigation bar. Specify this using html_short_title
in
conf.py
:
# conf.py
# By default the project value is used in the nav bar.
project = 'My Extra Special Amazing Docs'
# If specified, this will be used in the nav bar instead.
html_short_title = "Amazing Docs"
html_logo
¶
If you want to use a logo in the nav bar instead of text, specify html_logo
in conf.py
:
# conf.py
# It can either be a path to an image, relative to conf.py:
html_logo = './static/logo.png'
# Or it can be a URL:
html_logo = 'https://awesome.com/static/logo.png'
pygments_style
¶
We use the default
Pygments theme for syntax highlighting of code blocks.
It gives good results out of the box (including great dark mode support).
If you’d prefer to use a different Pygments style, you can specify it using
pygments_style
in conf.py
:
# conf.py
pygments_style = "stata-dark"
Dark Mode¶
When switching to dark mode, we automatically apply our own dark mode styles to code blocks. If you’d like to disable this behaviour, see dark_mode_code_blocks.
Theme specific¶
source_url
¶
If specified, a link is shown in the nav bar to the source code.
# conf.py
html_theme_options = {
"source_url": 'https://github.com/piccolo-orm/piccolo_theme/'
}
We try and detect if the URL points to GitHub or GitLab, and show the correct icon. However, if you’re using a self hosted version of GitHub or GitLab on a custom URL, you can explicitly tell the theme which icon to use:
# conf.py
html_theme_options = {
"source_url": 'https://self-hosted.foo.com/',
"source_icon": "gitlab"
}
The available options for source_icon
are:
generic
github
gitlab
dark_mode_code_blocks
¶
When switching to dark mode, we apply our own custom CSS styles to code blocks. This gives a great dark mode experience out of the box.
However, if you’ve specified a custom Pygments theme (see pygments_style), and you want to use that theme for both light mode and dark mode, you can disable our custom dark mode styles:
# conf.py
html_theme_options = {
"dark_mode_code_blocks": False,
}
show_theme_credit
¶
At the bottom of the page is a very small link which says Styled using the Piccolo Theme
.
This helps grow awareness of the project, and attract new contributors.
You can hide this if required:
# conf.py
html_theme_options = {
"show_theme_credit": False
}
If hiding it, please consider supporting us in a different way.