Changing buttons on page¶

Added in version 2022.02.14: Support for “edit this page” link.

Added in version 2024.05.06: Support for “view this page” link.

Furo can add buttons to each document that links visitors to the document’s sources on the repository’s source control system.

This feature is inherited from sphinx-basic-ng, specifically the view-this-page.html and edit-this-page components.

With popular VCS hosts¶

Provide the relevant VCS variables, by setting the following keys in html_theme_options:

html_theme_options = {
    "source_repository": "https://github.com/pradyunsg/furo/",
    "source_branch": "main",
    "source_directory": "docs/",
}

This model supports github.com, gitlab.com and bitbucket.org as domain names for the source_repository key.

With arbitrary URLs¶

Added in version 2022.09.29: source_edit_link

Added in version 2024.05.06: source_view_link

Use arbitrary URLs for the view/edit buttons, by setting the following keys in html_theme_options:

html_theme_options = {
    "source_edit_link": "https://my.awesome.host.example.com/awesome/project/edit/{filename}",
    "source_view_link": "https://my.awesome.host.example.com/awesome/project/view/{filename}",
}

The {filename} component will be replaced with the full path to the file, as known from the base of the documentation directory.

Important

Furo does not enforce that the source_edit_link / source_view_link contain {filename} or any sort of correctness check on these URLs. Make sure to manually confirm that the link works.

Linking to copied sources¶

If html_show_sourcelink and html_copy_source are True (which are the defaults), and the documentation does not configure any of the above variables, the view button will link to the raw sources copied in by Sphinx.

Read the Docs support¶

Added in version 2022.02.14.

Note

This feature is only available for projects hosted on GitHub.

Furo has built-in support for inferring details from Read the Docs’ environment for GitHub projects and enabling these buttons.

For such projects, Furo will try to automatically infer the source repository, branch, and directory from the Read the Docs build environment unless the above configuration variable are set.

Edit button on Read the Docs¶

The edit button will link to GitHub’s edit view for the document.

View button on Read the Docs¶

The view button will link to the raw sources copied in by Sphinx, if available, as noted above. If raw sources are not copied, it will link to GitHub’s plain view for the document.

If you do not want to link to copied sources, you can set the following in the conf.py:

html_copy_source = False
html_show_sourcelink = False

Disabling on Read the Docs¶

Added in version 2022.06.04.

Changed in version 2024.05.06: top_of_page_buttons replaces the singular top_of_page_button.

If you wish to disable these default buttons, use top_of_page_buttons and set it to [].