Furo主题文档顶部按钮自定义指南

Furo主题文档顶部按钮自定义指南

furo A clean customizable documentation theme for Sphinx 项目地址: https://gitcode.com/gh_mirrors/fu/furo

功能概述

Furo主题提供了在文档页面顶部添加实用按钮的功能，主要包括"编辑此页"和"查看源码"两个按钮。这些按钮可以帮助用户快速跳转到文档的源代码位置，便于贡献或查看原始内容。

基础配置方法

针对主流代码托管平台

对于GitHub、GitLab和Bitbucket等主流平台，可以通过以下配置实现自动生成按钮链接：

html_theme_options = {
    "source_repository": "平台仓库地址",
    "source_branch": "分支名称",
    "source_directory": "文档目录路径",
}

配置说明：

• source_repository：文档源代码仓库的完整URL
• source_branch：文档所在的分支名称（通常是main或master）
• source_directory：文档在仓库中的相对路径

自定义链接地址

如果需要使用非主流平台或自定义链接格式，可以直接指定编辑和查看链接：

html_theme_options = {
    "source_edit_link": "自定义编辑链接模板",
    "source_view_link": "自定义查看链接模板",
}

其中{filename}会被自动替换为文档的实际文件名。

高级功能配置

链接到复制的源码

当启用以下Sphinx默认配置时，查看按钮会链接到Sphinx复制的原始文档：

html_show_sourcelink = True  # 默认值
html_copy_source = True      # 默认值

Read the Docs平台集成

Furo针对Read the Docs平台提供了特殊支持：

1. 自动推断配置：在Read the Docs环境中，Furo会自动尝试从构建环境中获取GitHub仓库信息

2. 按钮行为：

   • 编辑按钮：指向GitHub的编辑界面
   • 查看按钮：优先指向Sphinx复制的源码，其次指向GitHub的原始文件视图

3. 禁用自动配置：如需禁用此功能，可设置：

html_theme_options = {
    "top_of_page_buttons": []
}

注意事项

1. 自定义链接模板必须包含{filename}占位符，系统不会自动验证链接格式的正确性

2. 在Read the Docs环境中，如需强制查看按钮指向GitHub而非复制的源码，需设置：

html_copy_source = False
html_show_sourcelink = False

3. 所有配置都应在html_theme_options字典中设置

通过合理配置这些选项，可以大大提升文档的可维护性和用户参与度，让文档协作变得更加便捷高效。

furo A clean customizable documentation theme for Sphinx 项目地址: https://gitcode.com/gh_mirrors/fu/furo