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

入门指南

1: 将Docsy作为Hugo模块使用

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

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

Get started - 入门指南

https://www.docsy.dev/docs/get-started/

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

正如我们在介绍中看到的，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模块，请遵循我们的迁移指南。如果您还没有准备好迁移，不要担心！您的站点将继续像往常一样工作。

设置指南

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

1 - 将Docsy作为Hugo模块使用

Use Docsy as a Hugo Module - 将Docsy作为Hugo模块使用

https://www.docsy.dev/docs/get-started/docsy-as-module/

学习如何通过将本主题作为 Hugo 模块使用来开始使用 Docsy。

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

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

使用 Hugo 模块的设置选项

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

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

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

1.1 - 开始之前

Before you begin - 开始之前

https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/

使用 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，请检查其版本：

1
hugo version

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

前往 Hugo releases 页面。
在最新版本中，向下滚动直到找到扩展版 Hugo 的列表。
下载最新的扩展版 Hugo（hugo_extended_0.1XX_Linux-64bit.tar.gz）。
创建一个新目录：
1
mkdir hugo
将下载的文件解压到 hugo 目录中。
切换到新的目录：
1
cd hugo
安装 Hugo：
1
sudo install hugo /usr/bin

在 macOS 上

使用 Brew安装 Hugo。

作为 `npm` 模块

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

1
npm install hugo-extended --save-dev

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

安装Go语言

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

1
2
$ go version
go version go1.19.2 windows/amd64

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

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

安装Git VCS客户端

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

1
2
$ git version
git version 2.39.1

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

安装PostCSS

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

1
2
npm install -D autoprefixer
npm install -D postcss-cli

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

1
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:

1
2
3
4
5
6
7
# 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:

1
2
3
4
5
# 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 - 创建新站点：从预设的站点开始

Create a new site: start with a prepopulated site - 创建新站点：从预设的站点开始

https://www.docsy.dev/docs/get-started/docsy-as-module/example-site-as-template/

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

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

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

TL;DR: 对于不耐烦的专家的设置

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

1
2
3
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）作为最后一个参数即可：

1
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。
1
git clone https://github.com/me-at-github/my-new-site.git

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

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

预览您的站点

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

1
2
cd my-new-site
hugo server

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

接下来呢？

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

Create a new site: Start a new site from scratch - 创建新站点：从头开始创建新站点

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

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

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

TL;DR: 专家快速设置

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

CLI:

=== “Unix shell”

```bash
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@v0.6.0
cat >> config.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy"
[[module.imports]]
path = "github.com/google/docsy/dependencies"
EOL
hugo server
```

=== “Windows command line”

```bash
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@v0.6.0
(echo [module]^

proxy = "direct"^

[[module.imports]]^

path = "github.com/google/docsy"^

[[module.imports]]^

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

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

详细设置说明

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

创建新的骨架项目

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

1
2
hugo new site my-new-site
cd  my-new-site

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

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

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

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

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

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

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

1
hugo mod get github.com/google/docsy@v0.6.0

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

添加主题模块配置设置

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

Configuration file:

=== “hugo.yaml”

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

=== “hugo.toml”

```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.imports]]
    path = "github.com/google/docsy/dependencies"
    disable = false
```

=== “hugo.json”

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

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

预览您的站点

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

1
hugo server

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

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

下一步是什么？

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

2 - 其他设置选项

Other setup options - 其他设置选项

https://www.docsy.dev/docs/get-started/other-options/

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

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

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

最后，您可以将 Docsy 安装为 NPM 包。

This guide provides instructions for all of these options, along with common prerequisites.

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

先决条件

安装 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）。
创建一个新目录：
1
mkdir hugo
提取您下载的文件到 hugo。
切换到新目录：
1
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 版本。例如：

1
node -v

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

1
nvm install --lts

安装PostCSS

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

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

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

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

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

对于新站点

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

创建站点：

1
2
3
hugo new site myproject
cd myproject
git init

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

对于已经存在的站点

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

将Docsy作为Git子模块安装：

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

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "...": "...",
  "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命令来构建和提供您的站点，例如：

1
hugo serve

选项2：克隆该Docsy主题

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

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

1
2
3
4
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指定为站点主题：

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

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

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

使用常规的Hugo命令构建或启动您的新站点，并指定Docsy主题文件的路径。例如，构建站点的命令如下：
1 2 3 4
$ hugo --themesDir node_modules Start building sites … ... Total in 1890 ms
你可以通过在站点的配置文件中添加本主题目录来删除 --themesDir ... 标志：
1
echo 'themesDir = "node_modules"' >> config.toml

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

1
2
3
4
mkdir -p themes
pushd themes
ln -s ../node_modules/docsy
popd

预览您的站点

要在本地预览您的站点：

1
2
cd myproject
hugo server

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

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

下一步是什么？

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

3 - 在 Docker 容器中部署 Docsy

Deploy Docsy inside a Docker container - 在 Docker 容器中部署 Docsy

https://www.docsy.dev/docs/get-started/quickstart-docker/

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

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

安装先决条件

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

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

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

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

构建并运行容器

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

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

Cleanup 清理

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

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

接下来是什么？

4 - 基本站点配置

Basic site configuration - 基本站点配置

https://www.docsy.dev/docs/get-started/basic-configuration/

新的 Docsy 站点的基本配置。

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

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

国际化

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

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

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

[languages.fa]
title = "اسناد گلدی"
description = "یک نمونه برای پوسته داکسی"
languageName ="فارسی"
contentDir = "content/fa"
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。或选择其他搜索选项。

下一步是什么？

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

5 - 已知问题

Known issues - 已知问题

https://www.docsy.dev/docs/get-started/known_issues/

在安装 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 解决方法

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

通过运行以下命令查看当前设置：
1
sudo launchctl limit maxfiles
通过运行以下命令将限制增加到65535个文件。如果您的站点文件较少，则可以选择设置较低的软（65535）和硬（200000）限制。
1 2 3 4
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挂载上运行，否则可能会出现意外错误。

入门指南

Get started - 入门指南

安装选项

迁移和向后兼容性

设置指南

1 - 将Docsy作为Hugo模块使用

Use Docsy as a Hugo Module - 将Docsy作为Hugo模块使用

使用 Hugo 模块的设置选项

1.1 - 开始之前

Before you begin - 开始之前

安装 Hugo

在 Linux 上

在 macOS 上

作为 npm 模块

安装Go语言

安装Git VCS客户端

安装PostCSS

安装/升级Node.js

接下来呢？

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

Create a new site: start with a prepopulated site - 创建新站点：从预设的站点开始

TL;DR: 对于不耐烦的专家的设置

详细设置说明

克隆 Docsy 示例站点

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

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

预览您的站点

接下来呢？

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

Create a new site: Start a new site from scratch - 创建新站点：从头开始创建新站点

TL;DR: 专家快速设置

详细设置说明

创建新的骨架项目

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

添加主题模块配置设置

预览您的站点

下一步是什么？

2 - 其他设置选项

Other setup options - 其他设置选项

先决条件

安装 Hugo

在 Linux 上

在 macOS 上

作为 NPM 模块

Node：获取最新 LTS 版本

安装PostCSS

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

对于新站点

对于已经存在的站点

选项2：克隆该Docsy主题

选项 3：Docsy 作为 NPM 包

预览您的站点

下一步是什么？

3 - 在 Docker 容器中部署 Docsy

Deploy Docsy inside a Docker container - 在 Docker 容器中部署 Docsy

安装先决条件

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

构建并运行容器

Cleanup 清理

接下来是什么？

4 - 基本站点配置

Basic site configuration - 基本站点配置

国际化

搜索

下一步是什么？

5 - 已知问题

Known issues - 已知问题

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`