欢迎来到Docsy

• 1: 入门指南
• 1.1: 将Docsy作为Hugo模块使用
• 1.1.1: 开始之前
• 1.1.2: 创建新站点：从预设的站点开始
• 1.1.3: 创建新站点：从头开始创建新站点
• 1.2: 其他设置选项
• 1.3: Docker中部署Docsy
• 1.4: 基本站点配置
• 1.5: 已知问题
• 2: 内容自定义
• 2.1: 添加内容
• 2.2: 颜色与字体
• 2.3: 导航和菜单
• 2.4: 搜索
• 2.5: 文档版本控制
• 2.6: Docsy简码
• 2.7: Logo和图片
• 2.8: 打印支持
• 2.9: 分析、用户反馈和SEO
• 2.10: 代码库链接及其页面信息
• 2.11: 分类支持
• 2.12: 图表和公式
• 3: 多语言支持
• 4: 预览和部署
• 5: 更新Docsy
• 5.1: 不使用Hugo模块更新Docsy
• 5.2: 使用子模块模块更新Docsy
• 5.3: 迁移到Hugo模块
• 6: 例子
• 7: 贡献指南
• 8: 最佳实践
• 8.1: Hugo内容提示
• 8.2: 组织你的内容

1 - 入门指南

​ 正如我们在介绍中看到的，Docsy是一个Hugo主题，这意味着如果您想使用Docsy，您需要设置您的站点源，以便Hugo静态站点生成器可以在构建站点时找到并使用Docsy主题文件。最简单的方法是复制和编辑我们的示例站点，尽管我们也提供了将Docsy主题手动添加到新站点或现有站点的说明。

​ 如果您想在本地构建和测试您的站点，您还需要能够运行Hugo本身，要么通过安装它和任何其他所需依赖项，要么使用我们提供的Docker容器。

本页面描述了Docsy的安装选项，并帮助您选择适当的设置指南以开始使用。

安装选项

​ Hugo提供了多种使用主题的选项，Docsy支持所有这些选项。

• 将主题添加为Hugo模块：Hugo模块是使用Hugo主题的最简单和最新的方式。Hugo使用模块机制从主Docsy仓库拉取主题文件，您可以选择版本，并且在您的站点中保持主题更新非常容易。我们的示例站点使用Docsy作为Hugo模块。
• 将主题添加为Git子模块：将主题作为Git子模块添加也可以让Hugo使用主题文件，尽管比Hugo模块方法更难维护。这是Docsy示例站点旧版本中使用的方法，现在仍然受支持。
• 克隆主题文件：如果您不想让Hugo从外部仓库获取主题文件（例如，如果您想直接自定义和维护主题的副本，或者您的部署选择需要您在仓库中包含主题的副本），您可以直接将文件克隆到您的站点源中。

迁移和向后兼容性

​ 如果您有一个使用Docsy作为Git子模块的现有站点，并希望将其更新为使用Hugo模块，请遵循我们的migration guide。如果您还没有准备好迁移，不要担心！您的站点将继续像往常一样工作。

设置指南

​ 按照您选择的方法的设置指南。如果您是Docsy的新手，并不确定要按照哪个指南，我们建议按照"将Docsy作为Hugo模块使用"指南，这是一种简单且易于维护的选择。

1.1 - 将Docsy作为Hugo模块使用

​ 在构建站点时，Hugo 模块是使用 Hugo 主题（如 Docsy）的最简单和最新的方法。Hugo 使用模块机制从您选择的版本中拉取主题文件，使得在站点中轻松地保持主题最新。我们的示例站点使用 Docsy 作为 Hugo 模块。

​ 要了解其他设置方法，请参阅我们的入门概述。如果您想将现有的 Docsy 站点迁移到使用 Hugo 模块，请查看我们的迁移指南。

使用 Hugo 模块的设置选项

​ 要将 Docsy 作为 Hugo 模块使用，您有以下几个选项：

• 复制并编辑 Docsy 示例站点的源代码。这种方法为您的站点提供了一个骨架结构，包括顶级和文档章节以及可根据需要修改的模板。示例站点使用 Docsy 作为 Hugo 模块。
• 使用 Docsy 主题构建自己的站点。在创建或更新站点时像任何其他 Hugo 主题一样指定 Docsy 主题。使用此选项，您将获得 Docsy 的外观和感觉、导航和其他功能，但需要指定自己的站点结构。

​ 如果您是初学者，我们建议您通过复制我们的示例站点来开始。如果您已经熟悉 Hugo 或想要非常不同的站点结构，您可以按照我们的指南从头开始创建站点，这样您就可以在较高的实现努力成本下获得最大的灵活性。在两种情况下，您需要遵循我们的先决条件指南，以确保您已安装了 Hugo 和所有必要的依赖项。

1.1.1 - 开始之前

​ 本页面描述了构建使用 Docsy 作为 Hugo 模块的站点。

安装 Hugo

​ 为了本地构建和预览使用 Docsy 的站点（比如这个示例站点），需要安 装最新的扩展版 Hugo（我们推荐使用版 本 0.73.0 或更高版本）。如果从发布页面进行安装，请确保获取的是支持 SCSS的扩展 版（extended） Hugo；你可能需要滚动到发布列表的末尾才能找到它。

​ 有关全面的 Hugo 文档，请参阅 gohugo.io。

在 Linux 上

​ 谨慎使用 sudo apt-get install hugo 命令进行安装，因为 它不能为所有 Debian/Ubuntu 版本提供扩展版 Hugo，也可能不是最新的版本。

​ 如果你已经安装了 Hugo，请检查其版本：

hugo version

​ 如果结果是 v0.109.0 或更早版本，或者看不到 Extended 字样，那么你需要安装最新 版本。在 Install Hugo 页 面中，可以查看完整的 Linux 安装选项。以下是从发布页面安装 Hugo 的方法：

1. 前往 Hugo releases 页面。

2. 在最新版本中，向下滚动直到找到扩展版 Hugo 的列表。

3. 下载最新的扩展版 Hugo（hugo_extended_0.1XX_Linux-64bit.tar.gz）。

4. 创建一个新目录：

   mkdir hugo
   

5. 将下载的文件解压到 hugo 目录中。

6. 切换到新的目录：

   cd hugo
   

7. 安装 Hugo：

   sudo install hugo /usr/bin
   

在 macOS 上

​ 使用 Brew安装 Hugo。

作为 npm 模块

​ 你可以使用 hugo-bin 将 Hugo 安装为 npm 模块。这将把hugo-bin添加到你的 node_modules 文件夹中，并将依赖项添加到 package.json 文件中。要安装 Hugo 的扩展版：

npm install hugo-extended --save-dev

​ 有关用法详细信息，请参阅hugo-bin 文档。

安装 Go 语言

​ Hugo 的模块管理命令需要在系统上安装 Go 编程语言。检查go是否已安装：

$ go version
go version go1.21.6

​ 确保您正在使用版本 1.12 或更高版本。

​ 如果go语言尚未安装在您的系统上，或者您需要升级它，请前往 Go 站点 的下载区域，选择适合您系统架构的安装程序并执行它。之后，检 查是否成功安装。

安装 Git VCS 客户端

​ Hugo 的模块管理命令需要在系统上安装git客户端。检查您的系统上是否已存 在git：

$ git version
git version 2.43.0

​ 如果您的系统上尚未安装git客户端，可以前往Git 站点， 下载适合您系统架构的安装程序并执行它。之后，检查是否成功安装。

安装 PostCSS

​ 要构建或更新站点的 CSS 资源，您还需要PostCSS来创建最终 的 assets。如果您需要安装它，则必须在您的计算机上安装最新版本的NodeJS，以便您可以使用npm，即 Node 包管理器。默认情况下，npm会在您运行npm install的目录下安装工具：

npm install -D autoprefixer
npm install -D postcss-cli

​ 从postcss-cli 的 8 版本开始，您还必须单独安装postcss：

npm install -D postcss

​ 请注意，如果全局安装 了PostCSS的版本大于 5.0.1，则不会加载autoprefixer，您必须使用本地安装。

安装/升级 Node.js

​ 为了确保您可以正确构建站点而不仅仅是执行hugo server，您必须安装最新的长期支持（LTS）版本的 Node.js。

如果您没有最新的 LTS 版本，则可能会看到以下错误之一：

Error: Error building site: POSTCSS: failed to transform "scss/main.css" (text/css): Unexpected identifier
#OR
/home/user/repos/my-new-site/themes/docsy/node_modules/hugo-extended/postinstall.js:1
import install from "./lib/install.js";
       ^^^^^^^

SyntaxError: Unexpected identifier
    at Module._compile (internal/modules/cjs/loader.js:723:23)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
    at Function.Module._load (internal/modules/cjs/loader.js:585:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)
    at startup (internal/bootstrap/node.js:283:19)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:623:3)

​ 您可以通过运行node -v来检查当前的 Node.js 版本。如果您需要安装新版本，请参阅 以下说明：

• 基于 Debian 和 Ubuntu 的发行版

  tl;dr:

  # Using Ubuntu
  curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
  sudo apt-get install -y nodejs
  
  # Using Debian, as root
  curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
  apt-get install -y nodejs
  

• 基于企业 Linux 的发行版

  tl;dr:

  # As root
  curl -fsSL https://rpm.nodesource.com/setup_18.x | bash -
  
  # No root privileges
  curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
  

接下来呢？

​ 在安装完所有必要的前提条件之后，选择如何开始你的新 Hugo 站点

• 从预设的站点开始（适合初学者）
• 从头开始创建站点（适合专家）

1.1.2 - 创建新站点：从预设的站点开始

​ 创建新 Docsy 站点的最简单方法是使用 Docsy 示例站点的源代码作为起点。这种方法为您的站点提供了一个骨架结构，包括顶层和文档章节以及您可以根据需要修改的模板。示例站点会自动作为 Hugo 模块引入 Docsy 主题，因此很容易保持最新状态。

​ 如果您更喜欢从头开始创建站点，请按照"从头开始创建站点（Start a site from scratch）“的说明进行操作。

快速设置

​ 在 Unix Shell 或 Windows 命令行中运行以下命令：

git clone https://github.com/google/docsy-example.git my-new-site
cd  my-new-site
hugo server

​ 现在，您可以在浏览器中预览 http://localhost:1313 中的新站点。

详细设置说明

克隆 Docsy 示例站点

​ 示例站点为您构建文档站点提供了一个很好的起点，并且预先配置为自动引入 Docsy 主题作为 Hugo 模块。有两种不同的方法可以获取示例站点的本地克隆：

• 如果您只想创建本地副本，请选择选项1。
• 如果您有 GitHub 帐户并希望为站点创建 GitHub 存储库，请选择选项2。

选项1：使用命令行（仅本地副本）

​ 如果您想使用除GitHub之外的远程存储库（例如GitLab、BitBucket、AWS CodeCommit、Gitea），或者根本不需要远程存储库，只需直接使用git clone创建一个本地工作副本，将您选择的本地存储库名称（此处为my-new-site）作为最后一个参数即可：

git clone https://github.com/google/docsy-example.git my-new-site

选项2：使用 GitHub UI（本地副本+关联的 GitHub 存储库）

​ 由于Docsy示例站点存储库是模板存储库，因此创建自己的远程GitHub克隆Docsy示例站点存储库非常容易：

1. 进入Docsy示例站点存储库，点击Use this template。

2. 选择新存储库的名称（例如my-new-site），并在Repository name字段中输入它。您还可以添加一个可选的Description。

3. 单击Create repository from template以创建新存储库。恭喜，您刚刚创建了远程Github克隆，现在它是您自己站点的起点！

4. 使用git clone创建您新创建的GitHub存储库的本地副本，并将其作为最后一个参数给出您的存储库的Web URL。

   git clone https://github.com/me-at-github/my-new-site.git
   

注意

​ 根据您的环境，您可能需要微调config.toml中的模块顶级设置，例如添加代理以在下载远程模块时使用。您可以在Hugo模块文档中找到这些配置设置的详细信息。

​ 现在，您可以对副本站点进行本地编辑并使用Hugo在本地进行测试。

预览您的站点

​ 要在本地构建和预览站点，请切换到克隆项目的根目录并使用Hugo的server命令：

cd my-new-site
hugo server

​ 在浏览器中预览站点：http://localhost:1313。由于Hugo的实时预览功能，您可以立即看到对本地存储库源文件进行更改的影响。您可以在任何时候使用Ctrl + c停止Hugo服务器。请参阅MacOS上的已知问题。

接下来呢？

• 添加一些基本配置
• 编辑现有内容并添加更多页面
• 自定义您的站点
• 发布您的站点。

1.1.3 - 创建新站点：从头开始创建新站点

​ 创建 Docsy 站点的最简单方法是复制我们的示例站点。但是，如果您是经验丰富的 Hugo 用户或者我们示例站点的站点结构不符合您的需求，您可能更喜欢从头开始创建新的站点。使用此选项，您将获得 Docsy 的外观和感觉、导航和其他功能，但您需要指定自己的站点结构。

​ 这些说明仅为您的站点项目提供最小的文件结构，以便您可以逐步构建和扩展您的实际站点。第一步是将 Docsy 主题作为 Hugo 模块添加到您的站点中。如果需要，您可以轻松地从 Docsy GitHub 存储库更新模块到最新版本。

快速设置

​ 在您的命令提示符下运行以下命令：

• CLI:
• Unix shell
• Windows command line

hugo new site my-new-site
cd  my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy@vmain
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy"
EOL
hugo server

hugo new site my-new-site
cd  my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy@vmain
(echo [module]^

proxy = "direct"^

[[module.imports]]^

path = "github.com/google/docsy") >> hugo.toml
hugo server

​ 现在，您可以在浏览器中预览您的新站点，网址为 http://localhost:1313。

详细设置

​ 将 Docsy 主题指定为最小站点的 Hugo 模块可为您提供所有主题的好处，但您需要指定自己的站点结构。

创建新项目

​ 要创建一个新的 Hugo 站点项目，然后将 Docs 主题作为子模块添加，从您的项目根目录运行以下命令。

hugo new site my-new-site
cd  my-new-site

​ 这将创建一个最小的站点结构，包含 archetypes、content、data、layouts、static 和 themes 文件夹以及一个配置文件（默认为 config.toml）。

将 Docsy主题模块作为站点的依赖项导入

​ 只有作为 Hugo 模块的站点才能导入其他模块。要将您的站点转换为 Hugo 模块，请在新创建的站点目录中运行以下命令：

hugo mod init github.com/me/my-new-site

​ 这将创建两个新文件，go.mod 用于模块定义，go.sum 用于保存模块校验和。

​ 接下来，将 Docsy 主题模块声明为站点的依赖项。

hugo mod get github.com/google/docsy@vmain

​ 此命令将 docsy主题模块添加到您的定义文件 go.mod 中。

添加主题模块设置

​ 在您的站点配置文件（默认：config.toml）的末尾添加以下片段中的设置并保存文件。

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

[module]
  proxy = "direct"

# uncomment line below for temporary local development of module

# replacements = "github.com/google/docsy -> ../../docsy"

  [module.hugoVersion]
    extended = true
    min = "0.73.0"
  [[module.imports]]
    path = "github.com/google/docsy"
    disable = false

module:
  proxy: direct
  hugoVersion:
    extended: true
    min: 0.73.0
  imports:
    - path: github.com/google/docsy
      disable: false

{
  "module": {
    "proxy": "direct",
    "hugoVersion": {
      "extended": true,
      "min": "0.73.0"
    },
    "imports": [
      {
        "path": "github.com/google/docsy",
        "disable": false
      }
    ]
  }
}

​ 您可以在Hugo模块文档中找到这些配置设置的详细信息。根据您的环境，您可能需要微调它们，例如添加代理以在下载远程模块时使用。

预览您的站点

​ 要在本地构建和预览网站：

hugo server

​ 默认情况下，您的网站将在 http://localhost:1313 上提供。如果遇到问题，请查看 已知问题（MacOS）。

​ 当您尝试构建网站时，您可能会遇到缺少参数和值的Hugo错误。这通常是因为您缺少Docsy使用的某些配置设置的默认值 —— 一旦您添加它们，您的网站就应该可以正确构建了。您可以在基本网站配置中了解如何添加配置 —— 即使您从头开始创建网站，我们建议复制示例网站配置，因为它为许多必需的配置参数提供了默认值。

下一步是什么？

• 添加一些基本配置

• 添加内容并自定义您的站点

• 从我们的示例站点和其他示例中获得一些想法。

• 发布您的站点.

1.2 - 其他设置选项

​ 如果您不想将 Docsy 用作 Hugo 模块（例如，如果您不想安装 Go），但仍不想将主题文件复制到自己的存储库中，则可以将 Docsy 用作 Git 子模块。使用子模块还允许 Hugo 使用 Docsy 存储库中的主题文件，但比 Hugo 模块方法更复杂。这是在旧版本的 Docsy 示例站点中使用的方法，目前仍然得到支持。如果您正在使用 Docy 作为子模块，但想迁移到 Hugo 模块，请参阅我们的迁移指南。

​ 另外，如果您不想让 Hugo 从外部存储库获取主题文件（例如，如果您想直接自定义和维护本主题的副本，或者您的部署选择要求您在存储库中包含本主题的副本），则可以将文件直接克隆到您的站点源。

​ 最后，您可以Docsy as an NPM package**.

​ 本指南提供了所有这些选项的说明，以及常见的先决条件。

先决条件

安装 Hugo

​ 要本地构建和预览使用 Docsy 的网站（如本示例网站），您需要一个最新的 extended 版本的Hugo（我们推荐使用 0.73.0 版本或更高版本）。如果您从发布页面安装，请确保获取支持 SCSS 的extended Hugo 版本；您可能需要滚动列表以查看它。

​ 有关全面的 Hugo 文档，请参见 gohugo.io。

在 Linux 上

​ 请注意，使用 sudo apt-get install hugo 可能不会为所有 Debian/Ubuntu 版本提供 extended 版本，而且可能不会与最新的 Hugo 版本保持同步。

​ 如果您已经安装了 Hugo，请检查您的版本：

hugo version

​ 如果结果是 v0.73 或更早版本，或者您没有看到 Extended，那么您需要安装最新版本。您可以在 安装 Hugo 中看到完整的 Linux 安装选项。以下是如何从发布页面安装 Hugo 的说明：

1. 转到 Hugo 发布页面。

2. 在最新版本中，向下滚动，直到找到扩展版本列表。

3. 下载最新的扩展版本（hugo_extended_0.9X_Linux-64bit.tar.gz）。

4. 创建一个新目录：

   mkdir hugo
   

5. 提取您下载的文件到 hugo。

6. 切换到新目录：

   cd hugo
   

7. 安装 Hugo：

   sudo install hugo /usr/bin
   

在 macOS 上

​ 使用 Brew安装 Hugo。

作为 NPM 模块

​ 您可以使用 hugo-extended 将 Hugo 安装为 NPM 模块。要安装 Hugo 的扩展版本：

npm install hugo-extended --save-dev

Node：获取最新 LTS 版本

​ 如果已经安装了 Node，请检查您的 Node 版本。例如：

node -v

​ 将您的Node版本安装或升级到活跃的LTS版本。我们建议使用nvm来管理您的Node安装（显示Linux命令）：

nvm install --lts

安装PostCSS

​ 要构建或更新站点的CSS资源，您还需要PostCSS。使用Node包管理器npm安装它。

重要提示：检查您的Node版本

​ 某些旧版本的Node安装的PostCSS软件包与Docsy不兼容。将您的Node版本与活动的LTS版本进行对比，并在必要时进行升级。有关详细信息，请参阅Node：获取最新的LTS版本。

​ 从您的项目根目录运行以下命令：

npm install --save-dev autoprefixer postcss-cli postcss

选项1：将Docsy作为Git子模块

对于新站点

​ 要创建一个新站点并将Docsy主题作为Git子模块添加，运行以下命令：

1. 创建站点：

   hugo new site myproject
   cd myproject
   git init
   

2. 按照先前的说明安装postCSS。

3. 按照下面的说明为现有站点进行操作。

对于已经存在的站点

​ 要将Docsy主题添加到现有站点，请从项目的根目录运行以下命令：

1. 将Docsy作为Git子模块安装：

   git submodule add https://github.com/google/docsy.git themes/docsy
   cd themes/docsy
   git checkout v0.6.0
   

   要从Docsy的开发版本中进行操作（不建议），请改为运行以下命令：

   git submodule add --depth 1 https://github.com/google/docsy.git themes/docsy
   

2. 将Docsy添加为主题，例如：

   echo 'theme = "docsy"' >> config.toml
   

   Tip

   在Hugo 0.110.0中，默认配置基础文件名更改为hugo.toml。如果您使用的是hugo 0.110或更高版本，请考虑将您的config.toml重命名为hugo.toml！

3. 获取Docsy依赖项：

   (cd themes/docsy && npm install)
   

4. （可选但建议）为了避免每次更新Docsy时都需要重复上一步操作，请考虑向项目的package.json文件添加以下NPM脚本：

   {
     "...": "...",
     "scripts": {
       "get:submodule": "git submodule update --init --depth 1",
       "_prepare:docsy": "cd themes/docsy && npm install",
       "prepare": "npm run get:submodule && npm run _prepare:docsy",
       "...": "..."
     },
     "...": "..."
   }
   

   每次从您的项目根目录运行npm install时，prepare脚本将获取Docsy及其依赖的最新版本。

​ 从这一点开始，使用通常的Hugo命令来构建和提供您的站点，例如：

hugo serve

选项2：克隆该Docsy主题

​ 如果您不想使用子模块（例如，如果您想直接自定义和维护本主题的副本，或者您的部署选择需要在存储库中包含本主题的副本），则可以将本主题克隆到项目的themes子目录中。

​ 将 Docsy 版本为 v0.6.0 的代码库克隆到你的项目的 themes 文件夹中，请在你的项目根目录下运行以下命令：

cd themes
git clone -b v0.6.0 https://github.com/google/docsy
cd docsy
npm install

​ 如果您想要使用 Docsy 的开发版本（不建议，除非您计划将更改上游（upstream ）到 Docsy），则省略上面的克隆命令中的 -b v0.6.0 参数。

​ 然后考虑设置一个 NPM prepare脚本，如选项 1 中所述。

​ 有关更多信息，请参阅Hugo网站上的Theme Components。

选项 3：Docsy 作为 NPM 包

​ 您可以按以下方式使用 Docsy 作为 NPM 模块：

1. 创建您的站点，并将Docsy指定为站点主题：

   hugo new site myproject
   cd myproject
   echo 'theme = "docsy"' >> config.toml
   

2. 安装Docsy和postCSS（按照之前的说明）：

   npm install --save-dev google/docsy#semver:0.6.0 autoprefixer postcss-cli postcss
   

3. 使用常规的Hugo命令构建或启动您的新站点，并指定Docsy主题文件的路径。例如，构建站点的命令如下：

   $ hugo --themesDir node_modules
   Start building sites …
   ...
   Total in 1890 ms
   

   你可以通过在站点的配置文件中添加本主题目录来删除 --themesDir ... 标志：

   echo 'themesDir = "node_modules"' >> config.toml
   

​ 作为指定 themesDir 的替代方法，在某些平台上，你可以按如下方式创建指向 Docsy 主题目录的符号链接（显示了 Linux 命令，从站点根文件夹执行）：

mkdir -p themes
pushd themes
ln -s ../node_modules/docsy
popd

预览您的站点

​ 要在本地预览您的站点：

cd myproject
hugo server

​ 默认情况下，您的站点将在 http://localhost:1313 上可用。有关MacOS上的已知问题，请参见已知问题。

​ 如果您在尝试构建站点时遇到缺少参数和值的 Hugo 错误，则通常是因为 Docsy 使用了某些配置设置的默认值而您没有它们，一旦您添加了它们，您的站点应该能够正确构建。有关如何添加配置的信息，请参见基本站点配置 —— 即使您从头开始创建站点，我们建议复制示例站点配置，因为它为许多必需的配置参数提供了默认值。

下一步是什么？

• Add some basic site configuration
• Add content and customize your site
• Get some ideas from our Example Site and other Examples.
• Publish your site.

1.3 - Docker中部署Docsy

​ 我们提供了一个 Docker 镜像，您可以使用它在本地运行和测试 Docsy 站点，而无需安装所有 Docsy 的依赖项。

安装先决条件

1. 在 Mac 和 Windows 上，下载并安装 Docker Desktop。在 Linux 上，安装 Docker engine 和 Docker Compose。

   安装可能需要您重新启动计算机以使更改生效。

2. 安装 git。

从 docsy-example 模板创建您的存储库

​ docsy-example 存储库提供了一个基本的站点结构，您可以将其用作创建自己的文档的起点。

1. 使用 docsy-example 模板 来 创建自己的存储库。

2. 通过 克隆新创建的存储库 将代码下载到本地计算机。

3. 将工作目录更改为新创建的文件夹：

   cd docsy-example
   

构建并运行容器

​ docsy-example 存储库包括一个 Dockerfile，您可以使用它来运行您的站点。

1. 构建 Docker 镜像：

   docker-compose build
   

2. 运行该构建的镜像：

   docker-compose up
   

3. 在您的 Web 浏览器中打开地址 http://localhost:1313 以加载 docsy-example 主页。现在您可以对源文件进行更改，在您的浏览器中进行实时重新加载。

Cleanup 清理

​ 要清理您的系统并删除容器镜像，请按以下步骤操作。

1. 使用 Ctrl + C 停止 Docker Compose。

2. 删除生成的镜像

   docker-compose rm
   

下一步是什么？

• Learn about basic setup and configurations for Docsy.
• Add content and customize your site
• Publish your site.

1.4 - 基本站点配置

​ 站点范围的配置细节和参数在项目的配置文件 (config.toml 或 hugo.toml) 中定义。这些包括你选择的 Hugo 主题（当然是 Docsy！）、项目名称、社区链接、Google Analytics 配置和 Markdown 解析器参数。在config.toml 的示例项目中查看带注释的示例，了解如何添加此信息。即使你只是使用主题而不是复制整个 Docsy 示例站点，我们建议复制此 config.toml 并进行编辑，因为它包括了许多参数的默认值，你需要设置这些参数才能正确构建站点。

​ 你可能想要立即删除或自定义复制的 config.toml 文件中的某些默认值：

国际化

​ 复制的 config.toml 文件定义了英语、挪威语和波斯语内容。你可以在 多语言支持 中了解 Docsy 如何支持多语言内容。

​ 如果你不打算翻译你的站点，可以通过从 config.toml 中删除以下行来删除语言切换器：

[languages.no]
languageName ="Norsk"
contentDir = "content/no"
[languages.no.params]
title = "Goldydocs"
description = "Docsy er operativsystem for skyen"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"

[languages.fa]
languageName ="فارسی"
contentDir = "content/fa"
[languages.fa.params]
title = "اسناد گلدی"
description = "یک نمونه برای پوسته داکسی"
time_format_default = "2006.01.02"
time_format_blog = "2006.01.02"

搜索

​ 默认情况下，Docsy 示例站点使用自己的谷歌自定义搜索引擎。要禁用此站点搜索，请删除或注释以下行：

# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "011737558837375720776:fsdu1nryfng"

​ 要使用您自己的自定义搜索引擎，请将 gcs_engine_id 中的值替换为您自己搜索引擎的 ID。或选择其他搜索选项.

下一步是什么？

• Add content and customize your site
• Get some ideas from our Example Site and other Examples.
• Publish your site.

configuration file

1.5 - 已知问题

​ 以下问题适用于 MacOS和 Windows Subsystem for Linux:

MacOS

Errors: too many open files or fatal error: pipe failed

​ 默认情况下，MacOS允许打开少量文件描述符。对于较大的网站或同时运行多个应用程序时，当您运行hugo server本地预览网站时，您可能会收到以下错误之一：

• POSTCSS v7 及更早版本：

  ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files
  

• POSTCSS v8 及更高版本：

  fatal error: pipe failed
  

Workaround 解决方法

​ 为了暂时允许更多的打开文件：

1. 通过运行以下命令查看当前设置：

   sudo launchctl limit maxfiles
   

2. 通过运行以下命令将限制增加到65535个文件。如果您的站点文件较少，则可以选择设置较低的软（65535）和硬（200000）限制。

   sudo launchctl limit maxfiles 65535 200000
   ulimit -n 65535
   sudo sysctl -w kern.maxfiles=200000
   sudo sysctl -w kern.maxfilesperproc=65535
   

​ 请注意，您可能需要为每个新的shell设置这些限制。了解有关这些限制及如何使其永久的更多信息。

Windows Subsystem for Linux (WSL)

​ 如果您正在使用WSL，请确保在文件系统的Linux挂载上运行hugo，而不是在Windows挂载上运行，否则可能会出现意外错误。

2 - 内容自定义

2.1 - 添加内容

​ 现在你有了一个带有 Docsy 的新 Hugo 站点，是时候添加一些内容了！本页面告诉你如何使用主题来添加和组织站点内容。

内容根目录

​ 你可以在你的 Hugo 站点项目的内容根目录下添加站点内容 - 即 content/ 或语言特定的根目录，比如 content/en/。这里的主要例外是你不想构建到站点中的静态文件：你可以在下面的添加静态内容中了解更多关于添加这些文件的位置。你的内容根目录中的文件通常按照站点章节和模板分组到子目录中，我们将在内容章节和模板中查看这些子目录。

​ 你可以在目录结构解释中了解有关 Hugo 目录结构的更多信息。

内容章节和模板

​ Hugo 使用你提供的内容文件和站点主题提供的任何模板来构建你的站点页面。这些模板（在 Hugo 术语中称为"layouts（布局）"）包括你的页面的页眉、页脚、导航和样式表链接：基本上除了页面的具体内容以外的一切。这些模板又可以由局部组成：用于页面元素（如页眉、搜索框等）的小型可重用 HTML 片段。

​ 因为大多数技术文档站点有不同的章节来存放不同类型的内容，Docsy 主题提供了以下顶级站点章节的模板：

• docs 用于你站点的文档章节的页面。
• blog 用于你站点的博客页面。
• community 用于你站点的社区页面。

​ 它还提供了一种默认的"着陆页"模板类型，带有站点页眉和页脚，但没有左侧导航，你可以用它来作为任何其他章节的模板。在这个站点和我们的示例站点中，它用于站点主页和About页面。

​ 你站点中的每个顶级章节都对应着站点内容根目录中的一个目录。根据内容所在的文件夹，Hugo 自动应用适当的模板来渲染该章节。例如，此页面位于站点内容根目录 content/en/ 的 docs 子目录中，因此 Hugo 自动应用 docs 模板。你可以通过显式指定特定页面的模板或内容类型来覆盖此行为。

​ 如果你复制了示例站点，则已经拥有适当命名的顶级章节目录来使用 Docsy 的模板，每个目录都有一个索引页面（ _index.md 或 index.html）供用户访问。这些顶级章节也会出现在示例站点的顶级菜单中。

自定义章节

​ 如果您复制了示例站点，但并不想使用提供的任何内容章节之一，只需删除相应的内容子目录即可。同样，如果您想添加一个顶级章节，只需添加一个新的子目录，但如果您想使用除默认模板之外的任何现有Docsy模板，则需要在每个页面的frontmatter中明确指定布局或内容类型。例如，如果您创建一个新目录content/en/amazing，并且希望该自定义章节中的一个或多个页面使用Docsy的docs模板，则在每个页面的前置元数据中添加type: docs：

• Front matter:
• toml
• yaml
• json

+++
title = "My amazing new section"
weight = 1
type = "docs"
description = '''
A special section with a docs layout.
'''
+++

---

title: "My amazing new section"
weight: 1
type: docs
description: >
  A special section with a docs layout  
---

{
  "title": "My amazing new section",
  "weight": 1,
  "type": "docs",
  "description": "A special section with a docs layout.\n"
}

​ 或者，根据现有模板，在您项目的layouts目录中为您的新章节创建自己的页面模板。

​ 您可以在Hugo模板中了解更多有关Hugo页面布局的工作原理。本页面的其余部分将告诉您如何添加内容并使用Docsy的每个模板。

替代站点结构

​ 如上所述，默认情况下，您的站点具有主页（使用_default布局），/docs/下的文档章节，/blog/下的博客章节和/community/下的社区章节。每个章节的类型（确定其使用的布局）与其目录名称匹配。

​ 在某些情况下，您可能希望具有不同的目录结构，但仍要利用Docsy的布局。一个常见的例子是"文档站点"，其中大多数页面（包括主页）都使用文档布局，或者您可能更喜欢将/news/目录视为博客布局。

​ 自Hugo 0.76以来，通过使用目标特定级联前置元数据，而不需要复制布局到您的站点或在每个页面上都指定type: blog，这已经变得可行。

​ 例如，对于/news/章节，您可以在index 页面中指定以下前置元数据，这将更改该章节及其以下所有内容的类型为"blog"：

• Front matter:
• toml
• yaml
• json

+++
title = "Latest News"
linkTitle = "News"

[menu.main]
weight = 30

[[cascade]]
type = "blog"
+++

---

title: "Latest News"
linkTitle: "News"
menu:
  main:
    weight: 30

cascade:

- type: "blog"

---

{
  "title": "Latest News",
  "linkTitle": "News",
  "menu": {
    "main": {
      "weight": 30
    }
  },
  "cascade": [
    {
      "type": "blog"
    }
  ]
}

​ 如果您想创建一个"docs"站点，则在顶级_index.md中指定类似以下内容将使所有顶级章节都被视为"文档"，除了"news"：

• Front matter:
• toml
• yaml
• json

+++
title = "My Wonderful Site"

[[cascade]]
type = "blog"
toc_root = true

  [cascade._target]
  path = "/news/**"

[[cascade]]
type = "docs"

[cascade._target]
  path = "/**"
+++

---

title: "My Wonderful Site"

cascade:

- type: "blog"
    toc_root: true
    _target:
    path: "/news/**"
- type: "docs"
    _target:
    path: "/**"

---

{
  "title": "My Wonderful Site",
  "cascade": [
    {
      "type": "blog",
      "toc_root": true,
      "_target": {
        "path": "/news/**"
      }
    },
    {
      "type": "docs",
      "_target": {
        "path": "/**"
      }
    }
  ]
}

请注意，这里增加了toc_root。将其设置为true，可以使其被视为站点的单独部分，具有自己的左侧导航菜单。

​ 使用此技术的示例基于文档的站点可在mostly docs repo中找到。

页面前置元数据

​ Hugo站点中的每个页面文件都有元数据前置元数据，告诉Hugo有关页面的信息。您可以在TOML、YAML或JSON中指定页面前置元数据（我们的示例站点和此站点使用YAML）。使用前置元数据指定页面标题、描述、创建日期、链接标题、模板、菜单权重，甚至包括页面使用的任何资源，如图像。您可以在前置元数据中查看可能的页面前置元数据的完整列表。

例如，这是本页面的前置元数据：

• Front matter:
• toml
• yaml
• json

+++
title = "Adding Content"
linkTitle = "Adding Content"
weight = 1
description = '''
Add different types of content to your Docsy site.
'''
+++

---

title: "Adding Content"
linkTitle: "Adding Content"
weight: 1
description: >
  Add different types of content to your Docsy site  
---

{
  "title": "Adding Content",
  "linkTitle": "Adding Content",
  "weight": 1,
  "description": "Add different types of content to your Docsy site.\n"
}

​ 你需要提供的最基本的前置元数据是title（标题）：其他的内容都由你决定！然而，如果你没有设置页面weight（权重），你的导航可能会有点混乱。你可能还想包括description，因为 Docsy 使用它来生成搜索引擎使用的mata description 标签。详见Search Engine Optimization (SEO) meta tags。

页面内容和标记

​ 默认情况下，你可以像编写普通的 Markdown 或 HTML 文件一样，在 Docsy 站点上创建页面并添加frontmatter，就像上面描述的那样。从 0.100 版本开始，Goldmark是 Hugo 唯一支持的 Markdown 解析器。

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

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

markup:
  goldmark:
    renderer:
      unsafe: true

{
  "markup": {
    "goldmark": {
      "renderer": {
        "unsafe": true
      }
    }
  }
}

​ 除了标记文本，你还可以使用 Hugo 和 Docsy 的 shortcodes（简码）：可重用的 HTML 片段，可以快速构建你的页面。在 Docsy Shortcodes 中了解更多关于简码的内容。

处理链接

​ Hugo 允许你使用普通的 Markdown 语法指定链接，但请记住，你需要将链接相对于你站点的根 URL 指定，而相对 URL 在你站点生成的 HTML 中不会被 Hugo 更改。

​ 或者，你可以使用 Hugo 的 helper ref 和 relref 简码来创建解析为正确 URL 的内部链接。但是，请注意，如果用户在你生成的站点之外查看你的页面，例如在 GitHub 的 Web UI 中使用渲染的 Markdown 功能，那么你的链接将根本不会出现为链接。

​ 你可以在 Hugo Tips 中找到（或添加！）有关处理 Hugo 链接的技巧和提示。

内容样式

​ 我们不强制要求您的页面内容采用任何特定的风格。然而，如果您需要一些关于如何编写和格式化清晰、简洁的技术文档的指导，我们推荐使用Google开发者文档风格指南，特别是其中的风格指南要点。

页面 bundles

​ 您可以将站点页面创建为其所在章节或子章节目录中的独立文件，或者作为包含内容的文件夹，其中内容在文件夹的index页中。为您的页面创建一个文件夹可以让您将图像和其他资源与内容捆绑（bundle）在一起。

​ 您可以在本站点和我们的示例站点中看到这两种方法的示例。例如，本页面的源代码只是一个独立的文件/content/en/docs/adding-content.md。然而，在本站点中，Docsy简码的源代码位于Docsy Shortcodes，该页面使用的图像资源位于同一个/shortcodes/目录中。在Hugo术语中，这被称为叶子bundle，因为它是一个文件夹，包含了单个站点页面的所有数据，没有任何子页面（并且使用了不带下划线的index.md）。

​ 您可以在页面Bundles中找到更多有关使用Hugo捆绑管理资源的信息。

Adding docs and blog posts

​ 您最常使用的模板可能是docs模板（如本页面所使用的）或非常相似的blog 模板。这两个模板都包括：

• a left nav
• GitHub链接（从您的站点配置中获取）供读者编辑页面或创建问题
• a page menu

以及所有站点页面都使用的常见页头和页脚。应用哪个模板取决于您是否将内容添加到blog或docs内容目录中。您可以在导航和搜索中了解有关如何创建导航和页面菜单的更多信息。

组织您的文档

​ 虽然Docsy的顶级章节允许您为不同类型的内容创建站点章节，但您可能还希望在docs章节内组织您的文档内容。例如，本站点的docs章节目录有多个子目录，用于入门、内容和自定义等。每个子目录都有一个_index.md（也可以是_index.html），它作为一个章节索引页，告诉Hugo相关目录是您的文档的子章节。

​ Docsy的docs布局为您提供了一个左侧导航窗格，其中包含根据您的文档文件结构自动生成的嵌套菜单。在docs/目录中的每个独立页面或子章节_index.md或_index.html页面都会获得一个顶级菜单项，使用页面或index中的链接名称和weight元数据。

​ 要向子章节添加文档，只需将页面文件添加到相应的子目录中。除子章节索引页面外，您添加到子章节的任何页面都将出现在子菜单中（请查看左侧以查看实际效果！），并按页面weight排序。在导航和搜索中了解有关添加Docsy导航元数据的更多信息。

​ 如果您已经复制了示例站点，则在您的docs目录中已经有一些建议的子目录，并提供了放置何种类型内容以及一些示例Markdown页面的指导。您可以在组织您的内容中了解更多关于使用Docsy组织内容的信息。

文档章节着陆页面

​ 默认情况下，文档章节着陆页（位于章节目录中的_index.md或_index.html）使用一种布局，该布局添加了一个格式化的链接列表，其中包含章节中的页面及其前置元数据描述。本站点中的内容和自定义着陆页面是一个很好的例子。

​ 要显示一个简单的链接条目列表，指定在着陆页面的前置元数据中simple_list: true：

• Front matter:
• toml
• yaml
• json

+++
title = "Simple List Page"
simple_list = true
weight = 20
+++

---

title: "Simple List Page"
simple_list: true
weight: 20
---

{
  "title": "Simple List Page",
  "simple_list": true,
  "weight": 20
}

To display no links at all, specify no_list: true in the landing page’s frontmatter:

• Front matter:
• toml
• yaml
• json

+++
title = "No List Page"
no_list = true
weight = 20
+++

---

title: "No List Page"
no_list: true
weight: 20
---

{
  "title": "No List Page",
  "no_list": true,
  "weight": 20
}

组织您的博客文章

​ Docsy的blog布局也为您提供了一个左侧导航菜单（如docs布局），以及应用于/blog/_index.md的列表类型index 页，自动按反向时间顺序显示所有最新文章的片段。

​ 要创建不同的博客类别以组织您的文章，请在blog/中创建子文件夹。例如，在我们的示例站点中，我们有news和releases。每个类别都需要有自己的_index.md或_index.html着陆页面文件，指定类别标题以使其在左侧导航和顶级博客着陆页面上正确显示。这是releases的index 页面：

• Front matter:
• toml
• yaml
• json

+++
title = "New Releases"
linkTitle = "Releases"
weight = 20
+++

---

title: "New Releases"
linkTitle: "Releases"
weight: 20
---

{
  "title": "New Releases",
  "linkTitle": "Releases",
  "weight": 20
}

To add author and date information to blog posts, add them to the page frontmatter:

• Front matter:
• toml
• yaml
• json

+++
date = 2018-10-06T00:00:00.000Z
title = "Easy documentation with Docsy"
linkTitle = "Announcing Docsy"
description = "The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch"
author = "Riona MacNamara"

[[resources]]
src = "**.{png,jpg}"
title = "Image #:counter"

[resources.params]
  byline = "Photo: Riona MacNamara / CC-BY-CA"
+++

---

date: 2018-10-06
title: "Easy documentation with Docsy"
linkTitle: "Announcing Docsy"
description: "The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch"
author: Riona MacNamara
resources:

- src: "**.{png,jpg}"
    title: "Image #:counter"
    params:
    byline: "Photo: Riona MacNamara / CC-BY-CA"

---

{
  "date": "2018-10-06T00:00:00.000Z",
  "title": "Easy documentation with Docsy",
  "linkTitle": "Announcing Docsy",
  "description": "The Docsy Hugo theme lets project maintainers and contributors focus on content, not on reinventing a website infrastructure from scratch",
  "author": "Riona MacNamara",
  "resources": [
    {
      "src": "**.{png,jpg}",
      "title": "Image #:counter",
      "params": {
        "byline": "Photo: Riona MacNamara / CC-BY-CA"
      }
    }
  ]
}

​ 如果您已经复制了示例站点，并且不想要blog 章节，或者想链接到外部博客，只需删除blog子目录即可。

使用顶级着陆页面

​ Docsy的默认页面模板没有左侧导航，适用于为您的站点或其他"着陆"类型页面创建主页。

自定义示例站点页面

​ 如果你已经复制了示例站点，那么在 content/en/_index.html 文件中你已经有了一个简单的站点着陆页。它由 Docsy 提供的 Hugo shortcode page blocks组成。

​ 要自定义大的着陆图片（在一个封面（cover）块中），请将项目中的 content/en/featured-background.jpg 文件替换为你自己的图片（文件名中必须包含background），你可以添加或删除尽可能多的块，以及添加你自己的内容。

​ 示例站点还有一个About 页面，在 content/en/about/_index.html 中使用相同的 Docsy 模板。同样，它由page blocks组成，包括 content/en/about/featured-background.jpg 中的另一个背景图片。与站点着陆页一样，你可以替换图片、删除或添加块，或者添加你自己的内容。

构建你自己的着陆页

​ 如果你刚刚使用了这个主题，你仍然可以使用所有 Docsy 提供的 page blocks（或任何其他你想要的内容）在相同的文件位置构建自己的着陆页。

添加community 页面

​ community着陆页模板有样板内容，自动填充项目名称和在 hugo.toml/hugo.yaml/hugo.json 中指定的社区链接，为你的用户提供快速访问资源的链接，帮助他们参与你的项目。同样的链接也默认添加到你的站点页脚。

Configuration file:

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

[params.links]

# End user relevant links. These will show up on left side of footer and in the community page if you have one

[[params.links.user]]
 name = "User mailing list"
 url = "<https://example.org/mail>"
 icon = "fa fa-envelope"
        desc = "Discussion and help from your fellow users"
[[params.links.user]]
 name ="Twitter"
 url = "<https://example.org/twitter>"
 icon = "fab fa-x-twitter"
        desc = "Follow us on Twitter to get the latest news!"
[[params.links.user]]
 name = "Stack Overflow"
 url = "<https://example.org/stack>"
 icon = "fab fa-stack-overflow"
        desc = "Practical questions and curated answers"

# Developer relevant links. These will show up on right side of footer and in the community page if you have one

[[params.links.developer]]
 name = "GitHub"
 url = "<https://github.com/google/docsy>"
 icon = "fab fa-github"
        desc = "Development takes place here!"
[[params.links.developer]]
 name = "Slack"
 url = "<https://example.org/slack>"
 icon = "fab fa-slack"
        desc = "Chat with other project developers"
[[params.links.developer]]
 name = "Developer mailing list"
 url = "<https://example.org/mail>"
 icon = "fa fa-envelope"
        desc = "Discuss development issues around the project"

params:
  links:
    user:
      - name: User mailing list
        url: '<https://example.org/mail>'
        icon: fa fa-envelope
        desc: Discussion and help from your fellow users
      - name: Twitter
        url: '<https://example.org/twitter>'
        icon: fab fa-x-twitter
        desc: Follow us on Twitter to get the latest news!
      - name: Stack Overflow
        url: '<https://example.org/stack>'
        icon: fab fa-stack-overflow
        desc: Practical questions and curated answers
    developer:
      - name: GitHub
        url: '<https://github.com/google/docsy>'
        icon: fab fa-github
        desc: Development takes place here!
      - name: Slack
        url: '<https://example.org/slack>'
        icon: fab fa-slack
        desc: Chat with other project developers
      - name: Developer mailing list
        url: '<https://example.org/mail>'
        icon: fa fa-envelope
        desc: Discuss development issues around the project

{
  "params": {
    "links": {
      "user": [
        {
          "name": "User mailing list",
          "url": "https://example.org/mail",
          "icon": "fa fa-envelope",
          "desc": "Discussion and help from your fellow users"
        },
        {
          "name": "Twitter",
          "url": "https://example.org/twitter",
          "icon": "fa-brands fa-x-twitter",
          "desc": "Follow us on Twitter to get the latest news!"
        },
        {
          "name": "Stack Overflow",
          "url": "https://example.org/stack",
          "icon": "fa-brands fa-stack-overflow",
          "desc": "Practical questions and curated answers"
        }
      ],
      "developer": [
        {
          "name": "GitHub",
          "url": "https://github.com/google/docsy",
          "icon": "fa-brands fa-github",
          "desc": "Development takes place here!"
        },
        {
          "name": "Slack",
          "url": "https://example.org/slack",
          "icon": "fa-brands fa-slack",
          "desc": "Chat with other project developers"
        },
        {
          "name": "Developer mailing list",
          "url": "https://example.org/mail",
          "icon": "fa fa-envelope",
          "desc": "Discuss development issues around the project"
        }
      ]
    }
  }
}

​ 如果你正在创建自己的站点，想要使用这个模板添加页面，请在你的内容根目录中添加一个 /community/_index.md 文件。如果你复制了示例站点，并不想要一个社区页面，请在项目存储库中删除 /content/en/community/ 目录。

添加静态内容

​ 你可能想要将一些非 Hugo 构建的内容与你的站点一起提供：例如，如果你使用 Doxygen、Javadoc 或其他文档生成工具生成参考文档。

​ 要添加静态内容以"原样（as-is）“提供，请在站点的 static 目录中添加文件夹和/或文件。在部署站点时，该目录中的内容将在站点根路径下提供服务。因此，例如，如果你在 /static/reference/cpp/ 添加了内容，用户可以在 http://{server-url}/reference/cpp/ 访问该内容，你可以从其他页面在 /reference/cpp/{file name} 上链接到该目录中的页面。

​ 你还可以在该目录中使用你的项目使用的其他文件，包括图像文件。你可以在静态文件中了解更多关于提供静态文件的信息，包括配置多个静态内容目录。

RSS 订阅

​ Hugo 默认会为主页和任何章节创建一个 RSS 订阅。对于主 RSS 订阅，你可以通过设置 hugo.toml/hugo.yaml/hugo.json 中的站点参数来控制包含哪些章节。这是默认配置：

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

[params]
rss_sections = ["blog"]

params:
  rss_sections: [blog]

{
  "params": {
    "rss_sections": [
      "blog"
      ]
  }
}

To disable all RSS feeds, add the following to your hugo.toml/hugo.yaml/hugo.json:

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

[params]
disableKinds = ["RSS"]

params:
  disableKinds: [RSS]

{
  "params": {
    "disableKinds": [
      "RSS"
      ]
  }
}

[outputs]
section = [ "HTML", "RSS", "print" ]

outputs:
  section:
    - HTML
    - RSS
    - print

{
  "outputs": {
    "section": [
      "HTML",
      "RSS",
      "print"
    ]
  }
}

Sitemap

​ Hugo默认为您的生成站点创建sitemap.xml文件：例如，这是本站的sitemap。

​ 您可以在hugo.toml/hugo.yaml/hugo.json中配置您的sitemap更新频率、sitemap文件名和默认页面优先级：

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

[sitemap]
  changefreq = "monthly"
  filename = "sitemap.xml"
  priority = 0.5

sitemap:
  changefreq: monthly
  filename: sitemap.xml
  priority: 0.5

{
  "sitemap": {
    "changefreq": "monthly",
    "filename": "sitemap.xml",
    "priority": 0.5
  }
}

To override any of these values for a given page, specify it in page frontmatter:

• Front matter:
• toml
• yaml
• json

+++
title = "Adding Content"
linkTitle = "Adding Content"
weight = 1
description = '''
Add different types of content to your Docsy site.
'''
[sitemap]
priority = 1
+++

---

title: "Adding Content"
linkTitle: "Adding Content"
weight: 1
description: >
  Add different types of content to your Docsy site.  
sitemap:
  priority: 1.0
---

{
  "title": "Adding Content",
  "linkTitle": "Adding Content",
  "weight": 1,
  "description": "Add different types of content to your Docsy site.\n",
  "sitemap": {
    "priority": 1
  }
}

​ 要了解有关配置站点地图的更多信息，请参阅Sitemap模板。

2.2 - 颜色与字体

​ 默认情况下，使用 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>

+++
title = "Welcome to Docsy"
linkTitle = "Documentation"

[menu.main]
weight = 20
pre = "<i class='fa-solid fa-book'></i>"
+++

---
title: "Welcome to Docsy"
linkTitle: "Documentation"
menu:
  main:
    weight: 20
    pre: <i class='fa-solid fa-book'></i>
---

{
  "title": "Welcome to Docsy",
  "linkTitle": "Documentation",
  "menu": {
    "main": {
      "weight": 20,
      "pre": "<i class='fa-solid fa-book'></i>"
    }
  }
}

[[menu.main]]
    name = "GitHub"
    weight = 50
    url = "https://github.com/google/docsy/"

menu:
  main:
    - name: GitHub
      weight: 50
      url: 'https://github.com/google/docsy/'

{
  "menu": {
    "main": [
      {
        "name": "GitHub",
        "weight": 50,
        "url": "https://github.com/google/docsy/"
      }
    ]
  }
}

[[menu.main]]
    name = "GitHub"
    weight = 50
    url = "https://github.com/google/docsy/"
    pre = "<i class='fa-brands fa-github'></i>"
    post = "<span class='alert'>New!</span>"

menu:
  main:
    - name: GitHub
      weight: 50
      url: 'https://github.com/google/docsy/'
      pre: <i class='fa-brands fa-github'></i>
      post: <span class='alert'>New!</span>

{
  "menu": {
    "main": [
      {
        "name": "GitHub",
        "weight": 50,
        "url": "https://github.com/google/docsy/",
        "pre": "<i class='fa-brands fa-github'></i>",
        "post": "<span class='alert'>New!</span>"
      }
    ]
  }
}

+++
title = "Navigation and Search"
linkTitle = "Navigation and Search"
date = 2017-01-05T00:00:00.000Z
weight = 3
description = '''
Customize site navigation and search for your Docsy site.
'''
+++

---
title: "Navigation and Search"
linkTitle: "Navigation and Search"
date: 2017-01-05
weight: 3
description: >
  Customize site navigation and search for your Docsy site.  
---

{
  "title": "Navigation and Search",
  "linkTitle": "Navigation and Search",
  "date": "2017-01-05T00:00:00.000Z",
  "weight": 3,
  "description": "Customize site navigation and search for your Docsy site.\n"
}

+++
title = "My Hidden Page"
weight = 99
toc_hide = true
hide_summary = true
description = '''
Page hidden from both the TOC menu and the section summary list.
'''
+++

---
title: "My Hidden Page"
weight: 99
toc_hide: true
hide_summary: true
description: >
  Page hidden from both the TOC menu and the section summary list.  
---

{
  "title": "My Hidden Page",
  "weight": 99,
  "toc_hide": true,
  "hide_summary": true,
  "description": "Page hidden from both the TOC menu and the section summary list.\n"
}

[params.ui]
sidebar_menu_compact = true
ul_show = 1
sidebar_menu_foldable = true
sidebar_cache_limit = 1000

params:
  ui:
    sidebar_menu_compact: true
    ul_show: 1
    sidebar_menu_foldable: true
    sidebar_cache_limit: 1000

{
  "params": {
    "ui": {
      "sidebar_menu_compact": true,
      "ul_show": 1,
      "sidebar_menu_foldable": true,
      "sidebar_cache_limit": 1000,
    }
  }
}

[params.ui]
breadcrumb_disable = true
taxonomy_breadcrumb_disable = true

params:
  ui:
    breadcrumb_disable: true
    taxonomy_breadcrumb_disable: true

{
  "params": {
    "ui": {
      "breadcrumb_disable": true,
      "taxonomy_breadcrumb_disable": true
    }
  }
}

{{ template "_default/_markup/td-render-heading.html" . }}

[params.ui]
sidebar_search_disable = true

params:
  ui:
    sidebar_search_disable: true

{
  "params": {
    "ui": {
      "sidebar_search_disable": true
    }
  }
}

#Enable offline search with Lunr.js
[params]
offlineSearch = true
offlineSearchSummaryLength = 200

params:
  offlineSearch: true
  offlineSearchSummaryLength: 200

{
  "params": {
    "offlineSearch": true,
    "offlineSearchSummaryLength": 200
  }
}

[params]
offlineSearch = true
offlineSearchMaxResults = 25

params:
  offlineSearch: true
  offlineSearchMaxResults: 25

{
  "params": {
    "offlineSearch": true,
    "offlineSearchMaxResults": 25
  }
}

.td-offline-search-results {
  max-width: 460px;
}

+++
title = "Index"
weight = 10
exclude_search = true
+++

---
title: "Index"
weight: 10
exclude_search: true
---

{
  "title": "Index",
  "weight": 10,
  "exclude_search": true
}

2.5 - 文档版本控制

定制多个文档版本的导航和横幅。

​ 根据您的项目的发布和版本控制，您可能希望让用户访问您的文档的先前版本。如何部署先前的版本取决于您。本页面介绍了 Docsy 中可用的功能，可用于在不同版本的文档之间提供导航，并在归档站点上显示信息横幅。

添加版本下拉菜单

​ 如果在 hugo.toml/hugo.yaml/hugo.json 中添加一些 [params.versions]，Docsy 主题将在顶级菜单中添加版本选择器下拉菜单。您可以指定每个版本的 URL 和名称，如下面的示例所示：

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

# Add your release versions here
[[params.versions]]
  version = "master"
  url = "https://master.kubeflow.org"

[[params.versions]]
  version = "v0.2"
  url = "https://v0-2.kubeflow.org"

[[params.versions]]
  version = "v0.3"
  url = "https://v0-3.kubeflow.org"

params:
  versions:
    - version: master
      url: 'https://master.kubeflow.org'
    - version: v0.2
      url: 'https://v0-2.kubeflow.org'
    - version: v0.3
      url: 'https://v0-3.kubeflow.org'

{
  "params": {
    "versions": [
      {
        "version": "master",
        "url": "https://master.kubeflow.org"
      },
      {
        "version": "v0.2",
        "url": "https://v0-2.kubeflow.org"
      },
      {
        "version": "v0.3",
        "url": "https://v0-3.kubeflow.org"
      }
    ]
  }
}

​ 记得添加当前版本，以便用户可以导航回去！

​ 版本下拉菜单的默认标题为 Releases。要更改标题，请更改 hugo.toml/hugo.yaml/hugo.json 中的 version_menu 参数：

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

[params]
version_menu = "Releases"

params:
  version_menu: Releases

{
  "params": {
    "version_menu": "Releases"
  }
}

​ 如果将 version_menu_pagelinks 参数设置为 true，则版本下拉菜单中的链接指向其他版本中的当前页面，而不是主页面。如果文档在不同版本之间几乎没有变化，则此功能可能很有用。请注意，如果其他版本中不存在当前页面，则链接将被broken。

​ 您可以在navigation and search.指南中阅读有关 Docsy 菜单的更多信息。

在归档的文档站点上显示横幅

​ 如果为文档的早期版本创建了归档快照，则可以在归档的文档的每个页面顶部添加注释，以让读者知道他们正在查看未维护的快照，并向他们提供最新版本的链接。

​ 例如，请参见 Kubeflow v0.6 的归档文档：

图1：Kubeflow v0.6归档文档上的横幅

​ 要在文档站点上添加横幅，请在hugo.toml/hugo.yaml/hugo.json文件中进行以下更改：

1. 将archived_version参数设置为true：

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

   [params]
   archived_version = true

   params:
     archived_version: true

   {
     "params": {
       "archived_version": true
     }
   }

2. 将version参数设置为归档文档集的版本。例如，如果归档文档是版本0.1：

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

   [params]
   version = "0.1"

   params:
     version: 0.1

   {
     "params": {
       "version": "0.1"
     }
   }

3. 确保url_latest_version包含您想要指向读者的站点的URL。在大多数情况下，这应该是您文档的最新版本的URL：

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

   [params]
   url_latest_version = "https://your-latest-doc-site.com"

   params:
     url_latest_version: https://your-latest-doc-site.com

   {
     "params": {
       "url_latest_version": "https://your-latest-doc-site.com"
     }
   }

\{\{\< blocks/cover title="Welcome!" image_anchor="center" height="full" color="primary" \>\}\}
<div class="mx-auto">
 <a class="btn btn-lg btn-primary me-3 mb-4" href="\{\{\< relref "/docs" \>\}\}">
  Learn More <i class="fa-solid fa-circle-right ms-2"></i>
 </a>
 <a class="btn btn-lg btn-secondary me-3 mb-4" href="https://example.org">
  Download <i class="fa-brands fa-github ms-2 "></i>
 </a>
 <p class="lead mt-5">This program is now available in <a href="#">AppStore!</a></p>
 <div class="mx-auto mt-5">
  \{\{\< blocks/link-down color="info" \>\}\}
 </div>
</div>
\{\{\< /blocks/cover \>\}\}

\{\{\% blocks/lead color="dark" \%\}\}
TechOS is the OS of the future.

Runs on **bare metal** in the **cloud**!
\{\{\% /blocks/lead \%\}\}

\{\{\< blocks/section color="dark" type="row" \>\}\}
\{\{\% blocks/feature icon="fa-lightbulb" title="Fastest OS **on the planet**!" \%\}\}
The new **TechOS** operating system is an open source project. It is a new project, but with grand ambitions.
Please follow this space for updates!
\{\{\% /blocks/feature \%\}\}
\{\{\% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" \%\}\}
We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
\{\{\% /blocks/feature \%\}\}
\{\{\% blocks/feature icon="fa-brands fa-twitter" title="Follow us on Twitter!" url="https://twitter.com/GoHugoIO" \%\}\}
For announcement of latest features etc.
\{\{\% /blocks/feature \%\}\}
\{\{\< /blocks/section \>\}\}

\{\{\% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" \%\}\}
We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
\{\{\% /blocks/feature \%\}\}

<div class="mx-auto mt-5">
 \{\{\< blocks/link-down color="info" \>\}\}
</div>