Customizing

The following code snippets can be set in conf.py to customize the appearance of your docs.

Project Name & Logo

Project name should be set both in Sphinx and in the theme. Logo options are set for the theme.

# This is used by Sphinx in many places, such as page title tags.
project = "My Project"

# These are options specifically for the Wagtail Theme.
html_theme_options = dict(
    project_name = "My Project",
    logo = "img/wagtail-logo-circle.svg",
    logo_alt = "Wagtail",
    logo_height = 59,
    logo_url = "/",
    logo_width = 45,
)

GitHub Link

The GitHub link is used for generating an “Edit on GitHub” button on each page. As such it should point to your docs folder in your default branch.

html_theme_options = dict(
    github_url = "https://github.com/wagtail/sphinx_wagtail_theme/blob/main/docs/"
)

Header & Footer Links

These will be shown in the bars at the top and bottom of the page.

Note that each setting is one long string, with entries separated by commas within the string. Each comma-separated entry uses a pipe | character to separate page title (left of pipe) from URL (right of pipe).

html_theme_options = dict(
    header_links = "Top 1|http://example.com/one, Top 2|http://example.com/two",
    footer_links = ",".join([
        "About Us|http://example.com/",
        "Contact|http://example.com/contact",
        "Legal|http://example.com/dev/null",
    ]),
 )

Show Copyright in Footer

This is a built-in Sphinx feature which will show the copyright notice in the footer of your docs.

copyright = "2021, My Company Inc."
html_show_copyright = True

Show Date Last Updated

This is a built-in Sphinx feature which will show the date the docs were last rendered in the footer of your docs. Format strings for Python’s strftime() are valid here. To disable, set to None

html_last_updated_fmt = "%b %d, %Y"

Custom Fonts & CSS

The theme ships with Adobe’s Source Sans and Source Code Pro fonts. You can change these, or any other style of the docs, with a custom CSS file.

Enable custom static files in conf.py:

# These folders are copied to the documentation's HTML output.
html_static_path = ["_static"]

# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...).
html_css_files = ["custom.css"]

Then in your _static/custom.css file, import a font and override the relevant rules:

/* Import from Google Fonts, a CDN, or files in your _static folder.
   This Google Fonts import provides its own `@font-face` CSS;
   if providing your own font files, you'll also need to
   provide your own `@font-face` code. */
@import url("https://fonts.googleapis.com/css2?family=Roboto");

/* Main font used throughout the docs. */
body {
  font-family: "Roboto", sans-serif;
}

/* Code snippets. */
pre, code, kbd, samp {
  font-family: "Courier New", monospace;
}

Customize the Sidebar

To change the contents of the sidebar, create a custom HTML template and specify it in conf.py. For example, let’s add a link to sponsor your project below the table of contents tree:

# Add any relative paths that contain templates.
templates_path = ["_templates"]

# Custom sidebar templates, must be a dictionary that maps document names
# to template names. "**" will apply the templates to all pages.
# The theme default is just searchbox and globaltoc.
html_sidebars = {"**": [
    "searchbox.html",
    "globaltoc.html",
    "custom.html",    # Your template here
]}

Then in _templates/custom.html:

<p>
  Sponsor my project!
  <a href="http://example.com">Here's the link</a>
</p>

Read more about customizing the sidebar in Sphinx