Configure the theme

Configure the Awesome Theme by changing one of the theme or extension options.

What’s the difference between theme and extension options?

Theme options: Are available in the HTML templates. They control layout and styling.
Extension options: Are defined in the Python code of the extensions. They can modify most of Sphinx behavior.

Theme options

To configure the theme, modify the html_theme_options dictionary in your Sphinx configuration.

pythonFile: conf.py

# Default values
html_theme_options = {
    "nav_include_hidden": True,
    "show_nav": True,
    "show_breadcrumbs": True,
    "breadcrumbs_separator": "/",
    "show_prev_next": False,
    "show_scrolltop": False,
    "extra_headerlinks": False,
}

nav_include_hidden

Controls whether to include entries from a hidden toctree directive in the sidebar.

By default, the toctree directive includes your content and generates a list of links in the content area of the page. With the hidden option, the content is still included, but no links are printed in the main content area.

show_nav

Controls whether to render the left sidebar.

show_breadcrumbs

Controls whether to include breadcrumbs links at the top of each page.

breadcrumbs_separator

The separator for the breadcrumbs links.

show_prev_next

Controls whether to show links to the previous and next pages in the hierarchy.

show_scrolltop

Controls whether to show a button that scrolls to the top of the page when clicked.

extra_header_links

Adds extra links to the header of your documentation.

The keys of the extra_header_links dictionary are the link texts. The values are absolute URLs.

Extension options

If you added the Awesome Theme as an extension, you can configure these options:

pythonFile: conf.py

html_collapsible_definitions = False
html_awesome_headerlinks = True
html_awesome_code_headers = True
html_awesome_docsearch = False
html_awesome_external_links = False

html_collapsible_definitions: Controls whether to make code objects, such as classes, collapsible.

Deprecated since version 4.1.0: Use the sphinx-design extension instead. This option will be removed in version 5.0.
html_awesome_headerlinks: Controls whether clicking a headerlink should copy the URL to the clipboard.

html_awesome_code_headers: Controls whether to show the highlighted programming language in the headers of code blocks.

Deprecated since version 4.1.0: This option will be removed in version 5.0.
html_awesome_docsearch: Controls whether to use Algolia DocSearch instead of the built-in search.
html_awesome_external_links: Controls whether to show an icon after external links.

New in version 4.1.0: In previous versions, this was always enabled.

Configure Algolia DocSearch

Algolia DocSearch is a third-party service. You need to apply and receive your credentials before you can use it.

You can configure DocSearch with the docsearch_config dictionary in your Sphinx configuration, by adding environment variables to your environment, or both. The environment variables have precedence.

Note

The Awesome Theme supports .env files for your environment variables.

pythonFile: conf.py

docsearch_config = {
    app_id: "",
    api_key: "",
    index_name: ""
    initial_query: "",
    placeholder: "",
    search_parameters: "",
    missing_results_url: ""
}

Algolia DocSearch credentials

You must provide these credentials, or DocSearch won’t work. The Sphinx project will still build, but the search won’t show any results.

app_id, DOCSEARCH_APP_ID: The id of your Algolia DocSearch application.
api_key, DOCSEARCH_API_KEY: The API key for searching your index on Algolia.
index_name, DOCSEARCH_INDEX_NAME: The name of your Algolia DocSearch index.

Optional DocSearch settings

initial_query, DOCSEARCH_INITIAL_QUERY

Provide a search query if you want to show search results as soon as the DocSearch modal opens.

New in version 4.1.0.

placeholder, DOCSEARCH_PLACEHOLDER

The placeholder for the search box. The default is: Search docs.

New in version 4.1.0.

search_parameters, DOCSEARCH_SEARCH_PARAMETERS

Search parameter for the Algolia Search.

New in version 4.1.0.

missing_results_url, DOCSEARCH_MISSING_RESULTS_URL

A URL for letting users send you feedback about your search. You can use the current query in the URL.

terminalExample for using missing_results_url

DOCSEARCH_MISSING_RESULTS_URL=https://github.com/example/docs/issues/new?title=${query}

Caution

Provide the URL as a string. DocSearch itself accepts a function. In the templates, the Awesome Theme creates the function with the string you entered.

New in version 4.1.0.