其他设置选项

  5 分钟阅读  

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 的说明：

  1. 转到 Hugo 发布页面。

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

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

  4. 创建一个新目录：

    1

    mkdir hugo

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

  6. 切换到新目录：

    1

    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 版本。例如：

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. 创建站点：

    1
2
3

    hugo new site myproject
cd myproject
git init

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

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

对于已经存在的站点

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

  1. 将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

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

    1

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

    提示

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

  3. 获取Docsy依赖项：

    1

    (cd themes/docsy && npm install)

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

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

    1
2
3

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

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

    1

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

  3. 使用常规的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 使用了某些配置设置的默认值而您没有它们，一旦您添加了它们，您的站点应该能够正确构建。有关如何添加配置的信息，请参见基本站点配置 —— 即使您从头开始创建站点，我们建议复制示例站点配置，因为它为许多必需的配置参数提供了默认值。

下一步是什么？

最后修改 May 22, 2023: 第一次提交 (d4e19f0)