颜色与字体

​ 默认情况下，使用 Docsy 的站点具有主题的默认字体、颜色和一般外观和感受。然而，如果您想要自己的颜色方案（您可能会想要！），您可以使用自己项目特定的值非常容易地覆盖主题默认值——Hugo 在查找构建您的站点的信息时将首先查找您的项目文件。并且，由于 Docsy 使用 Bootstrap 4 和 SCSS 进行样式化，您可以在其特殊的 SCSS 项目变量文件中仅覆盖单个值（如项目颜色和字体），或通过创建自己的样式进行更进一步的定制。

​ Docsy 还提供了使用 Chroma 或 Prism 进行高亮显示代码块的选项。

项目样式文件

​ 要自定义项目的外观和感受，请创建以下任一 Docsy 占位符文件的您自己的版本（注意下划线后缀 _project.scss）：

• assets/scss/_variables_project.scss 是您添加项目特定的主题变量定义（如站点颜色）以及您想要设置的任何其他 Bootstrap 变量值的地方。您可以在 assets/scss/_variables.scss 中找到 Docsy 主题变量及其默认值的列表。有关其他 Bootstrap 4 变量的信息，请参见变量默认值和 Bootstrap 的 v4-dev/scss/_variables.scss 文件。
• assets/scss/_styles_project.scss 是您可以添加自己的自定义 SCSS 样式的地方，包括覆盖 Docsy 主题 SCSS 文件中的任何样式。

颜色和主题颜色

站点颜色

要自定义站点的颜色，请将 SCSS 变量覆盖添加到**‘assets/scss/_variables_project.scss’**。例如，您可以设置主和辅助站点颜色如下：

$primary: #390040;
$secondary: #a23b72;

Docsy 具有 Bootstrap 功能，例如渐变背景（’$enable-gradients’） 和阴影 （’$enable-shadows’） 默认启用。这些也可以通过将变量设置为’假’。

要向 Bootstrap 的 [颜色映射表] 添加颜色或修改颜色，请使用 ‘assets/scss/_variables_project_after_bs.scss’。 例如：

$custom-colors: (
  'my-favorite-color': purple,
  'my-other-color': pink,
);

$theme-colors: map-merge($theme-colors, $custom-colors);

Learn how to modify maps, 请参阅 [Maps and loops] and [Adding theme colors].

[添加主题颜色]： https://getbootstrap.com/docs/5.3/customize/color-modes/#adding-theme-colors [彩色地图]：https://getbootstrap.com/docs/5.3/customize/color/#color-sass-maps [地图和循环]： https://getbootstrap.com/docs/5.3/customize/sass/#maps-and-loops [变量默认值]： https://getbootstrap.com/docs/5.3/customize/sass/#variable-defaults

Light/dark color themes

Docsy 0.10.0 支持浅色和 [深色模式] 颜色主题。允许您的网站用户选择浅色/深色模式，请启用 Docsy [浅色/深色菜单]** 或创建您自己的自定义主题选择器。

如果您的网站使用 [色度高亮显示代码]，则需要执行额外的步骤因此，代码块样式与浅色/深色模式兼容：

• 确保项目配置中的“markup.highlight.noClasses”为“false”。 有关此选项的详细内容，请参阅[生成语法荧光笔CSS]。
• 将 ‘@import ’td/code-dark’’ 添加到项目的 [’_styles_project.scss’] 文件中。

有关详细信息，请参阅[代码突出显示的色度]。

[代码高亮的色度]：#code-highlighting-with-chroma [浅色/深色菜单]：#lightdark 模式菜单 [生成语法突出显示CSS]： https://gohugo.io/content-management/syntax-highlighting/#generate-syntax-highlighter-css

字体

​ 该主题使用Open Sans 作为其主要字体。要禁用 Google Fonts 并使用系统字体，请在 assets/scss/_variables_project.scss 中设置此 SCSS 变量：

$td-enable-google-fonts: false;

​ 要配置其他 Google 字体：

$google_font_name: 'Open Sans';
$google_font_family: 'Open+Sans:300,300i,400,400i,700,700i';

​ 请注意，如果您决定选择具有不同权重的字体（在内置配置中，这是 300 (light), 400 (medium) and 700 (bold))，您还需要调整与权重相关的变量，即以 $font-weight- 开头的变量。

CSS 实用程序

​ 有关可用 CSS 实用程序类的文档，请参见 Bootstrap 文档。这个主题在这个领域自己添加的很少。但是，我们添加了一些颜色状态的 CSS 类，这些类在动态上下文中可能会很有用：

• .-bg-<color>
• .-text-<color>

​ 例如，当您不知道primary色是暗色还是亮色时，您可以使用这些类将文本样式为适当的颜色，以确保正确的颜色对比度。当您收到颜色代码作为shortcode参数时，它们也很有用。

​ <color> 的值可以是任何颜色名称，例如 primary、white、dark、warning、light、success、300、blue、orange 等。

​ 当您使用 .-bg-<color> 时，文本颜色将调整以获得适当的对比度：

<div class="-bg-primary p-3 display-4">Background: Primary</div>
<div class="-bg-200 p-3 display-4">Background: Gray 200</div>

To only set the text color use .-text-<color>:

<div class="-text-blue pt-3 display-6">Text: Blue</div>

使用Chroma进行代码高亮

Hugo’s default Chroma style is [monokai]. To use another style, such as [tango], add the following to your project configuration:

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[markup]
  [markup.highlight]
      style = "tango"

markup:
  highlight:
    style: tango

{
  "markup": {
    "highlight": {
      "style": "tango"
    }
  }
}

有关可用样式的完整列表，请参阅 [色度样式库]。

[色度风格库]：https://xyproto.github.io/splash/docs/ [monokai]：https://xyproto.github.io/splash/docs/monokai.html [OneDark]：https://xyproto.github.io/splash/docs/onedark.html [语法突出显示]： https://gohugo.io/content-management/syntax-highlighting/ [探戈]：https://xyproto.github.io/splash/docs/tango.html

浅色/深色代码样式

Docsy的默认色度样式 light/dark mode are:

• [tango] for light mode
• [onedark] for dark mode

如果您想使用其他样式，请将 [Hugo 生成的色度样式] 保存到相应的文件：

• assets/scss/td/chroma/_light.scss
• assets/scss/td/chroma/_dark.scss

没有指定语言的代码块

默认情况下，突出显示不会应用于没有指定语言。如果您希望将代码突出显示应用于 all 代码块，即使没有语言，也可以将“markup.highlight.guessSyntax”设置为“true”项目的配置文件。

复制到剪贴板

如果您使用的是 Docsy 0.6.0 或更高版本，代码块会显示“复制到剪贴板”右上角的按钮。要禁用此功能，请将配置文件中的“disable_click2copy_chroma”更改为“true”：

使用 Prism 突出显示代码

或者，您可以在’hugo.toml’/‘hugo.yaml’/‘hugo.json’：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params]
prism_syntax_highlighting = true

params:
  prism_syntax_highlighting: true

{
  "params": {
    "prism_syntax_highlighting": true
  }
}

启用此选项后，您的站点将使用 [棱镜]（https://prismjs.com/index.html） 代替 Chroma 作为代码块突出。

Prism 是一种流行的开源语法高亮显示，支持 200 多种 [语言]（https://prismjs.com/index.html#supported-languages）和各种 [插件]（https://prismjs.com/index.html#plugins）。

Docsy 包含用于基本 Prism 配置的 JavaScript 和 CSS 文件，其中支持：

• 使用 Prism “Default”主题设置样式的代码块
• 复制到代码块上的剪贴板按钮
• 多种常用语言的语法高亮显示，如按照 Prism 下载链接，[自定义您的下载][prismjs-download+]。

prismjs-下载+

没有语言的代码块

默认情况下，Prism 代码突出显示样式不应用于代码块如果没有指定的语言，你会得到 Docsy 的默认灰色样式黑色文本。将 Prism 样式应用于没有语言或有语言的代码块Prism 不支持，请在三元组后指定“none”作为语言反引号。

为其他语言或插件扩展 Prism

如果随附的棱镜配置不足以满足您的要求，并且您想使用其他语言或插件，您可以替换包含的文件。

1. 下载您自己的 Prism JS 和 CSS 文件 https://prismjs.com/download.html
2. 将包含的 Prism JS 和 CSS 替换为您下载的文件：
   • 将 Javascript 文件复制到 ‘static/js/prism.js’
   • 将 CSS 文件复制到 ‘static/css/prism.css’

导航栏

设置项目徽标和名称的样式

默认的 Docsy 导航栏 （’.td-navbar’） 显示您的站点标识，包括以下各项：

1. Your logo，它以内联 SVG 的形式包含在导航栏中，样式为 ‘.td-navbar .navbar-brand svg’。有关样式的详细信息，请参阅 _nav.scss。

为确保您的徽标正确显示，您可能需要调整其大小并确保它没有高度和宽度属性，因此其大小是完全的响应。[覆盖默认样式][项目样式] 的 ‘.td-navbar .navbar-brand svg’ 或（等效） ‘.td-navbar .navbar-brand__logo’（.td-navbar .navbar-’）。

2. 您的项目名称，即网站“标题”。如果你不想要你的项目要显示的名称（例如，因为您的徽标是或包含 [文字商标][]），然后将以下自定义样式添加到 [项目的styles][项目样式]：

   .td-navbar .navbar-brand__name {
     display: none;
   }
   

浅色/深色模式菜单

如果启用此功能，Docsy 会在导航栏中添加一个菜单，让用户在默认的“轻量级”模式之间切换您网站的文档页面显示，以及“深色”模式，其中文本在深色上以浅色显示背景。

若要在导航栏中启用浅色/[深色模式]菜单的显示，请设置“params.ui.showLightDarkModeMenu”在项目的配置文件中设置为“true”。下拉菜单显示在右，紧挨着 [搜索框]（如果存在）。

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params]
[params.ui]
showLightDarkModeMenu = true

params:
  ui:
    showLightDarkModeMenu: true

{
  "params": {
    "ui": {
      "showLightDarkModeMenu": true
    }
  }
}

半透明封面图像

对于包含 blocks/cover 短代码的页面，与大多数主页一样，导航栏是半透明的，只要主图没有向上滚动到导航栏。有关示例，请参阅 [关于 Docsy][] 页面。这个初始半透明设置确保主图像的最大可见度。

主图滚动过导航栏后，导航栏的（不透明）背景颜色被设置为 – 通常设置为网站的 [原色][]。

使用某些英雄图像，导航栏条目的文本可能难以阅读。在在这些情况下，您可以通过设置“params.ui.navbar_translucent_over_cover_disable”选项更改为“true”站点的 [配置文件][]。

表格

Docsy通过类’.td-table’将以下样式应用于所有表：

• Bootstrap table styles:
  • .table
  • .table-striped
  • .table-responsive
• display: block, which is necessary for tables to be responsive.

此样式配置为您提供仅使用 Markdown 的响应式表，无需将表包裹在“

| Shape    | Number of sides |
| -------- | --------------- |
| Triangle | 3               |
| Square   | 4               |
{.td-initial .my-dark-table-style}

layouts/partials/hooks/head-end.html

layouts/partials/hooks/body-end.html

<!doctype html>
<html lang="{{ .Site.Language.Lang }}" class="no-js">
  <head>
    {{ partial "head.html" . }}
  </head>
  <body class="td-{{ .Kind }}">
    <header>
      {{ partial "navbar.html" . }}
    </header>
    <div class="container-fluid td-default td-outer">
      <main role="main" class="td-main">
        {{ block "main" . }}{{ end }}
      </main>
      {{ partial "footer.html" . }}
    </div>
    {{ partialCached "scripts.html" . }}
  </body>
</html>