Furo主题颜色自定义完全指南

Furo主题颜色自定义完全指南

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

前言

Furo是一款现代化的Sphinx文档主题，以其出色的可定制性著称。本文将深入讲解如何通过CSS变量来自定义Furo主题的颜色方案，包括浅色和深色模式下的各种配置技巧。

颜色系统工作原理

Furo采用了一套智能的颜色管理系统：

1. 默认模式：Furo默认使用浅色模式
2. 自动切换：当用户浏览器设置为深色模式时(prefers-color-scheme: dark)，主题会自动切换
3. 继承机制：深色模式继承浅色模式的变量定义，仅覆盖需要调整的值

这种设计确保了两种模式间的一致性，同时提供了足够的灵活性。

自定义颜色配置

基础配置方法

在项目的conf.py文件中，通过html_theme_options配置项可以定义CSS变量来覆盖默认值：

html_theme_options = {
    "light_css_variables": {
        "color-brand-primary": "#7C4DFF",  # 主品牌色
        "color-brand-content": "#7C4DFF", # 内容链接色
    },
}

常用颜色变量

Furo提供了丰富的颜色变量供开发者自定义：

• color-brand-primary: 主品牌色(用于侧边栏等)
• color-brand-content: 内容链接色
• color-background-primary: 主背景色
• color-background-secondary: 次要背景色
• color-foreground-primary: 主前景(文字)色
• color-foreground-secondary: 次要前景色

深色模式特殊处理

如果需要为深色模式单独设置颜色，可以添加dark_css_variables配置：

html_theme_options = {
    "light_css_variables": {
        "color-brand-primary": "#7C4DFF",
    },
    "dark_css_variables": {
        "color-brand-primary": "#9E7CFF",  # 深色模式下更亮的紫色
    },
}

代码块样式定制

Furo将代码高亮样式交由Sphinx处理，可以通过以下配置自定义：

# 浅色模式代码样式
pygments_style = "sphinx"

# 深色模式代码样式(Furo特有配置)
pygments_dark_style = "monokai"

推荐搭配：

• 浅色模式：sphinx, pastie, friendly
• 深色模式：monokai, native, paraiso-dark

图片等媒体资源的处理

对于需要在不同模式下显示不同效果的图片，可以使用特定的CSS类：

<img src="light.png" class="only-light">
<img src="dark.png" class="only-dark">

这种方式特别适合处理带有背景的图片，确保在不同模式下都能获得最佳显示效果。

高级技巧

1. 间距调整：除了颜色，还可以通过变量调整各种间距

   "light_css_variables": {
       "spacing-1": ".5rem",
       "spacing-2": "1rem",
   }
   

2. 完整覆盖：可以完全重写所有颜色变量，创建全新的主题风格

3. 响应式设计：某些变量可以针对不同屏幕尺寸设置不同值

总结

Furo主题提供了极其灵活的颜色定制方案，从简单的品牌色更换到完整的主题重构都能轻松实现。通过合理使用CSS变量和Sphinx配置，开发者可以创建出既符合品牌形象又保证用户体验的文档主题。

建议在实际项目中先从小范围的颜色调整开始，逐步扩展到更全面的自定义，这样可以更好地控制主题的整体效果。

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