这是本节的多页打印视图。点击此处打印.

入门指南

学习如何开始使用Docsy，包括安装和使用Docsy主题的可用选项。

1: 将Docsy作为Hugo模块使用

1.1: 开始之前
1.2: 创建新站点：从预设的站点开始
1.3: 创建新站点：从头开始创建新站点

2: 其他设置选项
3: Docker中部署Docsy
4: 基本站点配置
5: 已知问题

正如我们在介绍中看到的，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 - 将Docsy作为Hugo模块使用

将主题作为 Hugo模块使用来开始使用 Docsy。

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

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

使用 Hugo 模块的设置选项

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

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

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

1.1 - 开始之前

使用 Docsy 作为 Hugo 模块构建站点。

本页面描述了构建使用 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 的方法：

前往 Hugo releases 页面。
在最新版本中，向下滚动直到找到扩展版 Hugo 的列表。
下载最新的扩展版 Hugo（hugo_extended_0.1XX_Linux-64bit.tar.gz）。
创建一个新目录：
```
mkdir hugo
```
将下载的文件解压到 hugo 目录中。
切换到新的目录：
```
cd hugo
```
安装 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.2 - 创建新站点：从预设的站点开始

通过使用 Docsy 示例站点的克隆作为起点来创建新的 Hugo 站点。

创建新 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示例站点存储库非常容易：

进入Docsy示例站点存储库，点击Use this template。
选择新存储库的名称（例如my-new-site），并在Repository name字段中输入它。您还可以添加一个可选的Description。
单击Create repository from template以创建新存储库。恭喜，您刚刚创建了远程Github克隆，现在它是您自己站点的起点！
使用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.3 - 创建新站点：从头开始创建新站点

使用 Docsy 作为 Hugo 模块从头开始创建新的 Hugo 站点

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

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

快速设置

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

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）。

Tip

在 Hugo 0.110.0 中，默认配置文件的基本文件名已更改为 hugo.toml。如果您使用的是 hugo 0.110 或更高版本，请考虑将 config.toml 重命名为 hugo.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）的末尾添加以下片段中的设置并保存文件。

[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使用的某些配置设置的默认值 —— 一旦您添加它们，您的网站就应该可以正确构建了。您可以在基本网站配置中了解如何添加配置 —— 即使您从头开始创建网站，我们建议复制示例网站配置，因为它为许多必需的配置参数提供了默认值。

下一步是什么？

添加一些基本配置
添加内容并自定义您的站点
从我们的示例站点和其他示例中获得一些想法。
发布您的站点.

2 - 其他设置选项

使用Git或NPM创建一个新的Docsy站点

如果您不想将 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 的说明：

转到 Hugo 发布页面。
在最新版本中，向下滚动，直到找到扩展版本列表。
下载最新的扩展版本（hugo_extended_0.9X_Linux-64bit.tar.gz）。
创建一个新目录：
```
mkdir hugo
```
提取您下载的文件到 hugo。
切换到新目录：
```
cd hugo
```
安装 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子模块添加，运行以下命令：

创建站点：

hugo new site myproject
cd myproject
git init

按照先前的说明安装postCSS。
按照下面的说明为现有站点进行操作。

对于已经存在的站点

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

将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

将Docsy添加为主题，例如：
```
echo 'theme = "docsy"' >> config.toml
```
Tip
在Hugo 0.110.0中，默认配置基础文件名更改为hugo.toml。如果您使用的是hugo 0.110或更高版本，请考虑将您的config.toml重命名为hugo.toml！
获取Docsy依赖项：
```
(cd themes/docsy && npm install)
```

（可选但建议）为了避免每次更新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 模块：

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

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

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

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

使用常规的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.

3 - Docker中部署Docsy

使用 Docker 镜像可以在本地运行和测试 Docsy 站点，无需安装所有 Docys 依赖项。

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

安装先决条件

在 Mac 和 Windows 上，下载并安装 Docker Desktop。在 Linux 上，安装 Docker engine 和 Docker Compose。
安装可能需要您重新启动计算机以使更改生效。
安装 git。

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

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

使用 docsy-example 模板来创建自己的存储库。
通过克隆新创建的存储库将代码下载到本地计算机。
将工作目录更改为新创建的文件夹：
```
cd docsy-example
```

构建并运行容器

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

构建 Docker 镜像：
```
docker-compose build
```
运行该构建的镜像：
```
docker-compose up
```
在您的 Web 浏览器中打开地址 http://localhost:1313 以加载 docsy-example 主页。现在您可以对源文件进行更改，在您的浏览器中进行实时重新加载。

Cleanup 清理

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

使用 Ctrl + C 停止 Docker Compose。
删除生成的镜像
```
docker-compose rm
```

下一步是什么？

4 - 基本站点配置

Docsy 站点的基本配置

站点范围的配置细节和参数在项目的配置文件 (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

5 - 已知问题

安装 Docsy 主题时的已知问题

以下问题适用于 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 解决方法

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

通过运行以下命令查看当前设置：
```
sudo launchctl limit maxfiles
```
通过运行以下命令将限制增加到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挂载上运行，否则可能会出现意外错误。

入门指南

安装选项

迁移和向后兼容性

设置指南

1 - 将Docsy作为Hugo模块使用

使用 Hugo 模块的设置选项

1.1 - 开始之前

安装 Hugo

在 Linux 上

在 macOS 上

作为 npm 模块

安装 Go 语言

安装 Git VCS 客户端

安装 PostCSS

安装/升级 Node.js

接下来呢？

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

快速设置

详细设置说明

克隆 Docsy 示例站点

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

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

预览您的站点

接下来呢？

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

快速设置

详细设置

创建新项目

Tip

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

添加主题模块设置

预览您的站点

下一步是什么？

2 - 其他设置选项

先决条件

安装 Hugo

在 Linux 上

在 macOS 上

作为 NPM 模块

Node：获取最新 LTS 版本

安装PostCSS

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

对于新站点

对于已经存在的站点

Tip

选项2：克隆该Docsy主题

选项 3：Docsy 作为 NPM 包

预览您的站点

下一步是什么？

3 - Docker中部署Docsy

安装先决条件

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

构建并运行容器

Cleanup 清理

下一步是什么？

4 - 基本站点配置

国际化

搜索

下一步是什么？

5 - 已知问题

MacOS

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

Workaround 解决方法

Windows Subsystem for Linux (WSL)

作为 `npm` 模块

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