定制

Alabaster的行为和风格可以通过多种方式进行自定义:

  • 可以通过您的配置各种模板级或非平凡样式的设置 conf.py 在里面 html_theme_options主题选项 .

  • 从Alabaster 0.7.8开始,您可以通过 custom stylesheet 。这适用于只需要少量CSS修改的更改。

    注解

    在0.7.8之前实现的一些主题选项更适合作为本地自定义样式表覆盖。因此:

    • 我们不再接受通过使用此功能更合适地解决的功能请求。

    • 在将来的向后不兼容版本中,我们可能会弃用其中一些选项;因此,我们强烈建议尽可能利用自定义样式表,即使下面提供了一个选项。

自定义样式表

如果需要修改Alabaster的默认CSS样式,则可以按如下方式提供自定义CSS样式表,该方式未包含在下一节的主题选项中:

  • 创建名为 custom.css 任何您喜欢的地方(通常 _static/ ,但这完全是约定),其中包含您想要的对Alabaster中的CSS的覆盖 static/alabaster_css_t .

  • 设置核心Sphinx选项 html_static_path 添加到该文件的路径或其所在的目录。

主题选项

Alabaster的主要配置路线是 html_theme_options 变量,设置在 conf.py 在睡觉沿线,例如:

html_theme_options = {
    'logo': 'logo.png',
    'github_user': 'bitprophet',
    'github_repo': 'alabaster',
}

以下小节详细介绍了可用的此类选项,包括有关行为的说明。可通过查看找到默认值 theme.conf 直接。

基础

与文本显示、徽标等相关的设置。

  • body_text_align :哪个CSS text-align 要用于正文文本的值(如果有)。

  • canonical_url :如果设置,则用作的基URL(设置在相对路径/页面名之前 <link rel="canonical"> canonical URL 标题标签。

    注解

    该值必须以尾随的劈开结尾。

  • description :有关您的项目的文本格式回复信息,显示在徽标下面。

  • description_font_style :哪个CSS font-style 用于描述文本。

  • fixed_sidebar :使侧边栏“固定”或固定到位,以便页面主体滚动,但侧边栏保持可见。(仅适用于桌面窗口大小;移动视图不受影响。)

  • logo :相对路径(从 $PROJECT/_static/ )转换为徽标图像,该图像将出现在项目名称上方的左上角。

    • 如果 logo 未设置,则您的 project 名称设置(来自顶层Sphinx配置)将在文本标题中使用。这将保留从内部文档页面返回到您主页的链接。

  • logo_name :设置为 true 要插入您的站点的 project 徽标图像下的名称为文本。如果您的徽标不包括项目名称本身,则非常有用。

  • logo_text_align :哪个CSS text-align 用于徽标文本的值(如果有。)

  • page_width :控制默认内容/页面宽度的CSS宽度说明符。

  • sidebar_width :控制默认边栏宽度的CSS宽度说明符。

  • touch_icon :图像的路径(与 logo ,相对于 $PROJECT/_static/ )用于iOS应用程序图标,用于通过Safari将页面保存到iOS设备的主屏幕。

非服务侧边栏控件

与服务链接没有直接关系的侧栏相关选项。

  • extra_nav_links :字典将链接名称映射到链接目标;这些将添加到主边栏导航下方的UL中(前提是您已启用 navigation.html 通过 html_sidebars 选项;见 安装 。)对于Sphinx文档树外部的静电链接非常有用。

  • show_related :控制侧栏“下一个/上一个/相关”辅助导航元素是隐藏还是显示的布尔值。默认为 false 因为在许多网站上,这些元素是多余的。

    注解

    这与 show_relbars 页眉/页脚选项中的设置;这两个可视组件是正交的,可以彼此独立地启用/禁用。

  • sidebar_collapse :确定是否所有符合以下条件的目录条目都是布尔值

    不是当前页的祖先,则会折叠。您可以在Sphinx Toctree中阅读更多关于这方面的内容 docs .

  • sidebar_includehidden :确定TOC侧栏是否应该包含隐藏的Sphinx toctree元素的布尔值。默认为 true 所以你可以使用 :hidden: 在你的索引页面的根目录树中&避免在你的登录页面上有2倍的导航副本。

样式颜色

这些应该是完全限定的CSS颜色说明符,例如 #004B6B#444 。列表中的前几项是用作其他许多项的默认值的“全局”颜色;更新这些项以对配色方案进行彻底更改。可以根据需要使用更精细的设置来覆盖。

  • anchor :节锚链接的前景色(将鼠标悬停在页面节标题上时显示的‘段落’符号。)

  • anchor_hover_bg :背景颜色 anchor 文本。

  • anchor_hover_fg :鼠标悬停在节锚点链接上时的前景色(如上所述)。

  • body_text :主要内容文本。

  • code_highlight :使用时突出显示的颜色 :emphasize-lines: 代号挡路。

  • footer_text :页脚文本(包括链接。)

  • footnote_bg :脚注块的背景。

  • footnote_border :相同的边框。

  • gray_1 :深灰色。

  • gray_2 :浅灰色。

  • gray_3 :中灰色。

  • link_hover :主体链接,悬停。

  • link :未悬停的躯干链接。

  • narrow_sidebar_bg :当窄窗口将“侧边栏”强制放到页面底部时,“侧边栏”的背景。

  • narrow_sidebar_fg :相同的文本颜色。

  • narrow_sidebar_link :链接颜色相同。

  • note_bg :背景: .. note:: 阻碍。

  • note_border :相同的边框。

  • pink_1 :浅粉色。

  • pink_2 :中粉色。

  • pre_bg :预格式化文本块的背景(包括代码段。)

  • relbar_border :钢筋夹持之间的边框颜色 nextprevious 链接,以及睡觉的页面内容。

  • seealso_bg :背景: .. seealso:: 阻碍。

  • seealso_border :相同的边框。

  • sidebar_header :侧栏标题。

  • sidebar_hr :侧栏水平标尺分隔符的颜色。

  • sidebar_link :侧边栏链接(没有悬停变体。)适用于页眉和文本链接。

  • sidebar_list :侧栏列表项目符号和未链接文本的前景色。

  • sidebar_link_underscore :侧栏链接的下划线(严格地说是底部边框)。

  • sidebar_search_button :搜索字段的“Go”按钮的背景色。

  • sidebar_text :侧栏段落文本。

  • warn_bg :背景: .. warn:: 阻碍。

  • warn_border :相同的边框。

字体

  • caption_font_size :字幕挡路文本的字体大小。

  • caption_font_family :字幕挡路文本的字体系列。

  • code_font_size :代码挡路文本的字体大小。

  • code_font_family :字体家族代码挡路文字。默认为 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace .

  • font_family :正文文本的字体系列。

  • font_size :正文文本的字体大小。

  • head_font_family :标题的字体系列。默认为 'Garamond', 'Georgia', serif .