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

将Docsy作为Hugo模块使用

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

1: 开始之前
2: 创建新站点：从预设的站点开始
3: 创建新站点：从头开始创建新站点

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

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

使用 Hugo 模块的设置选项

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

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

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

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 站点

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上的已知问题。

接下来呢？

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

下一步是什么？

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

将Docsy作为Hugo模块使用

使用 Hugo 模块的设置选项

1 - 开始之前

安装 Hugo

在 Linux 上

在 macOS 上

作为 npm 模块

安装 Go 语言

安装 Git VCS 客户端

安装 PostCSS

安装/升级 Node.js

接下来呢？

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

快速设置

详细设置说明

克隆 Docsy 示例站点

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

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

预览您的站点

接下来呢？

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

快速设置

详细设置

创建新项目

Tip

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

添加主题模块设置

预览您的站点

下一步是什么？

作为 `npm` 模块