Default Sphinx configuration¶

Sphinx projects are configured through a build configuration file named conf.py. The Sphinx Stack ships with the following configuration to support its default behavior and features:

Required configuration¶

Project, repository, and site metadata¶

The Project Information section contains settings for your project’s official name, Open Graph Protocol (OGP) metadata, and global variables that are passed into the Sphinx context across your entire site.

Configuration setting	Description
`project`	Specifies the official name of your project.
`ogp_site_name`, `ogp_image`	Defines the preview website name and preview image.
`html_favicon`	Defines the small icon shown in the browser tab, bookmarks, and sometimes the browser history for your documentation.
`html_context`	Specifies a dictionary of custom values that Sphinx passes into the HTML template rendering context, including: Product website links (`product_page`) Community or contact links (`discourse`, `mattermost`, `matrix`) Documentation source and issue integration (`github_url`, `repo_default_branch`, `repo_folder`, `github_issues`) UI behavior (`sequential_nav`, `display_contributors`) Footer and license metadata (`author`, `license`)
`html_theme_options`	Sets options that the HTML theme reads when rendering pages.

Sitemap¶

Configuration setting	Description
`html_baseurl`	Specifies the base URL of your documentation website.
`sitemap_url_scheme`	Determines how page URLs are formed. It is set to `'{link}'` by default. This uses the value of `html_baseurl` to generate the full URL for each page for the sitemap.
`sitemap_show_lastmod`	Specifies whether to include the last modification time in the sitemap.
`sitemap_excludes`	Lists the non-public pages to be excluded from the sitemap. Wildcards are supported. For details, see Excluding Pages.

To understand how the Sphinx Stack generates sitemaps, see Sitemaps. For instructions on supporting versioned documentation, see Manage sitemaps for versioned documentation.

sphinx-llm extension¶

llms_txt_description specifies the short description included in the llms.txt file generated by the sphinx_llm.txt extension.

Sphinx link checker¶

Configuration settings in the Link checker exceptions section tell Sphinx which URLs to skip, which anchor checks to relax, and how persistent to be when a request is slow or fails.

Configuration setting	Description
`linkcheck_ignore`	Lists the URLs to ignore entirely. Use this configuration setting when the whole link is unreliable or intentionally excluded.
`linkcheck_anchors_ignore_for_url`	Lists anchor fragments to ignore for matching URLs. Use this configuration setting when the page is valid, but its section anchors are not worth verifying.
`linkcheck_timeout`	Specifies how long in seconds to wait for a response before timing out
`linkcheck_retries`	Specifies how many times to retry failures

Feedback button¶

Configuration setting	Description
`html_context["github_url"]`	Specifies the URL of the GitHub repository where feedback issues are created.
`disable_feedback_button`	Disables the feedback button when set to `True`.
`html_context["feedback_link"]`	Set this if your team doesn’t use GitHub issues for feedback. This setting takes precedence over the link constructed with `github_url` if set.

Optional configuration¶

The Sphinx Stack contains several features that you can configure or turn off if they aren’t suitable for your documentation.

HTML templates¶

The Sphinx Stack provides default header and footer templates. The templates_path setting specifies the directories that Sphinx searches for project-specific templates.

For information about how to create your own templates, see Use custom HTML templates.

Redirects¶

Configuration setting	Description
`rediraffe_redirects`	Specifies redirect mappings either as a dictionary or as the path, relative to `conf.py`, to a file containing the mappings.
`rediraffe_dir_only`	Controls whether redirect destination URLs omit `/index.html`. When set to `True`, destination URLs use directory-style paths.

For instructions on adding redirect mappings, see Redirect pages.

Extensions¶

Configuration setting	Description
`extensions`	Lists the Sphinx extensions enabled for the documentation project. Each extension must be installed in the documentation build environment.

For extensions included with the Sphinx Stack, see Default Sphinx extensions.

Extension support

The only extensions formally supported by the Sphinx Stack are those included in its default requirements.txt file.

UI behavior¶

The sequential_nav key in html_context controls which Previous and Next navigation buttons are displayed at the bottom of pages. Valid values are:

Value	Description
`both`	Both the Previous and Next buttons are shown at the bottom.
`none`	No Previous or Next button is shown at the bottom.
`prev`	Only the Previous button is shown at the bottom.
`next`	Only the Next button is shown at the bottom.

For page-specific navigation settings, see Add page-specific configuration.