保持文档最新状态可能是一个耗时且令人沮丧的手动过程。但一种称为“文档即代码”（Documentation as Code）的方法可以通过自动化、版本控制等来简化流程。在本指南中，@ezinne_anne 将解释如何使用 Docusaurus 和 GitHub Actions 将文档设置为代码。https://freecodecamp.org/news/set-up-docs-as-code-with-docusaurus-and-github-actions/…

如何使用 Docusaurus 和 GitHub Actions 将文档设置为代码

来源：https://www.freecodecamp.org/news/set-up-docs-as-code-with-docusaurus-and-github-actions/

对于技术写作人员来说，手动保持文档最新状态可能非常令人沮丧。过时的指南、损坏的链接和缺失的更新等问题很令人头疼，并且可能降低写作效率。这些问题还会使用户更难有效地使用文档并获取正确的信息。

文档即代码（Documentation as Code）是一种将文档视为代码库来管理的方法。它允许你像在代码库中一样对文档进行版本控制、自动更新和审查。文档即代码有助于确保文档保持最新，并且用户能够获取准确的信息。

本教程将向你展示如何：

• 使用 Docusaurus 创建文档网站。
• 使用 Git 和 GitHub 跟踪更改。
• 构建并将其部署到托管平台。
• 设置一个工作流，在合并更改之前使用 GitHub Actions 进行语法审查。

先决条件

本教程适合初学者，但仍需具备一些工具或知识：

• VSCode IDE（或你选择的其他 IDE）（https://code.visualstudio.com/download）。
• 已安装 Node.js 和 npm。（https://docs.npmjs.com/downloading-and-installing-node-js-and-npm）
• 一个 GitHub 账户。（https://github.com/）
• 合理掌握如何使用 Git 和 GitHub。（https://www.freecodecamp.org/news/gitting-things-done-book/）

为什么技术写作人员要使用文档即代码？

在深入探讨之前，让我们先快速讨论一下“文档即代码”是什么以及为什么重要。

早在 2015 年，Google 的两位技术写作人员提出了这个想法，目的是让开发人员更容易为文档做出贡献，并更好地组织公司文档。有时他们需要编写正在开发的应用程序，但一切都很混乱。于是他们想出了这个方法。自那时起，许多公司采用了这种方法。

文档即代码如今是一种流行的文档管理方法，许多工具都支持它，这些工具旨在将文档视为代码来处理。Tom Johnson 在他的文章（https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html）中更详细地解释了这一概念。

传统文档依赖于 Word 文档和 PDF，更改通过手动跟踪或文档修订历史记录。写作人员必须手动更新和发布内容，无法自动化日常任务。另一方面，文档即代码借鉴了软件开发的原则和工具，使文档更加结构化、版本化和自动化。文档存储在版本控制（如 Git）中，使用轻量级标记语言编写，并随代码一起更新。这种方法确保文档与软件同步演进，保持高质量，并允许高效协作，就像编写代码一样。

本教程将使用的工具

让我们回顾一下本教程使用的主要工具：

1. Docusaurus 是由 Facebook 创建的工具，用于创建文档网站。它支持 Markdown 和 MDX，还支持版本控制和自定义主题，便于创建用户友好且专业的文档。
2. Vale 是一个可自定义的风格和语法检查器，适用于写作人员。它确保技术文档中的语言、语气和风格保持一致。除 Vale 之外，还有其他良好的 linter 可供审查使用，但这里我们使用 Vale。
3. GitHub Actions：一种 CI/CD 工具，用于直接在 GitHub 中自动化工作流。它可以帮助你轻松测试、构建和部署代码。

步骤 1：安装 Docusaurus

打开命令行终端并输入以下命令：

npx create-docusaurus@latest docs-as-code-tutorial classic

docs-as-code-tutorial 是我为网站使用的名称。如果需要，你可以将其替换为任何其他网站名称。选择 JavaScript 作为你想要使用的语言。这将开始创建一个新的 Docusaurus 站点。

运行代码后，你将看到 docs-as-code-tutorial 文件夹出现在你的 VSCode 工作区中。导航到该文件夹。

接下来，启动开发服务器，以便查看你的文档。

cd docs-as-code-tutorial
npm start

这样，站点将开始在 localhost:3000 运行。当你查看站点时，会看到预先生成的内容。因此，在下一步中，你将创建一个仓库并将本地文件夹链接到远程仓库。

Docusaurus 主页

步骤 2：创建仓库

现在，你需要为 docs-as-code-tutorial 创建一个仓库。前往你的 GitHub 账户并创建一个新仓库。

创建仓库后，你需要将仓库链接到 VSCode 工作区中的文件夹。打开一个新终端并运行以下命令：

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/myname/docs-as-code-tutorial.git
git push -u origin main

这样，你就已链接了仓库，Git 将开始跟踪你的更改。

步骤 3：在 docusaurus.config 文件中自定义文档

在开始自定义之前，创建一个分支，以便在推送到主分支时进行更改。

git checkout -b "new_branch"

docusaurus.config.js 文件是你可以对站点进行大部分编辑的地方。将 title 属性更改为 Docs as code。

const config = {
  title: 'Docs as code',
  tagline: 'Documentation as code',
  //rest of your code
  navbar: {
    title: 'Docs as code',
    //rest of your code
  }
}

预览文档时，这将显示为新标题。这只是一个示例，用于演示 Docusaurus 的工作方式。你可以根据需要进一步自定义站点，但这里我们不再详细讨论（因为本教程的主要目的是展示如何将文档设置为代码）。

c4dab104-9f8b-4dad-a3a5-250d15d4552d

进行更改后，站点应该会略有不同。你现在可以推送更改。

git commit -am "first commit"
git push --set-upstream origin new_branch

步骤 4：编辑文档

在本教程中，我将在 docs 部分进行编辑。转到 intro.md，并将 Markdown 文本替换为以下内容：

# How to set up docs-as-code
Documentation-as-code is a great means to push changes made in your local machine to your docs live site.
To accomplish this, you need an IDE, a static site generator, a Git repository, CI/CD to set up workflows, and a hosting platform.

## Why do technical writers do docs-as-code?
Documentation-as-code is a great means to push changes made in your local machine to your docs live site.
To accomplish this, you need an IDE, a static site generator, a Git repository, CI/CD to set up workflows, and a hosting platform.

进行编辑后，预览你的文档。

intro.md 显示上述内容

步骤 5：添加 Linting 功能

将 Vale linter 添加到你的文档中以审查错误。为此，可使用以下任一命令安装 Vale CLI。

• 在 Windows 上运行 choco install vale
• 在 macOS 上运行 brew install vale
• 在 Linux 上运行 snap install vale

如何设置 Vale

正如我之前提到的，Vale 是一种可自定义的风格和语法检查工具。这意味着你可以根据你的需求来设置它以审查文档。Vale 在执行审查时会使用 Vale 风格指南来发现错误并提出建议。但如果你愿意，你也可以将公司风格指南或任何其他风格指南添加进去。有一些公开的风格指南可供使用，例如 Google 风格指南、Microsoft 风格指南等。在本教程中，我们将使用 Microsoft 风格指南。

如果你还没有该指南，则需要获取 Microsoft 风格指南（https://github.com/errata-ai/Microsoft/releases/download/v0.7.0/Microsoft.zip），下载并解压。创建一个 styles 文件夹，并将 Microsoft 文件夹移动到 styles 文件夹中。你的文件路径应如下：

- docs-as-code-tutorial
  //other folders
- styles
  - Microsoft
//other folders

在文档中创建一个 .vale.ini 文件，并将其添加到根目录。在其中添加以下代码：

StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Vale, Microsoft

让我们理解一下这里的内容：

• StylesPath 设置为 styles 文件夹，即你存放下载的 Microsoft 风格指南的位置。MinAlertLevel 将 Vale 警报设置为 suggestion —— 这意味着 Vale 将突出显示文档中的建议、警告和错误。如果 MinAlertLevel 设置为 errors，则 Vale 仅突出显示错误。如果设置为 warnings，则它将突出显示警告和错误（依此类推）。
• [*.md] 告诉 Vale 只检查 .md 文件。
• BasedOnStyles 指示你用于 linting 的风格指南。在本例中，是 Microsoft 风格指南和 Vale 风格指南。因此，当 linter 运行时，它将使用指定的风格指南突出显示建议、警告和错误。

要测试文档，请运行 vale intro.md（假设你仍有 intro.md 文件）。输出应如下：

✔ 0 errors, 0 warnings and 0 suggestions in stdin.

步骤 6：构建站点

为此，运行 npm run build。之后，你可以使用 npm run serve 预览构建。

步骤 7：部署站点

有许多托管平台可以托管你的在线站点。本教程涵盖两种托管选项：GitHub Pages 和 Netlify。

使用 GitHub Pages 部署

要部署到 GitHub Pages，你需要在 docusaurus.config.js 文件中设置仓库名称和 GitHub 用户名/组织名称。

// Set the production url of your site here
url: 'https://ezinneanne.github.io/',
// Set the
// pathname under which your site is served
// For GitHub pages deployment, it is often '//'
baseUrl: '/docs-as-code-tutorial/',

// GitHub pages deployment config.
// If you aren't using GitHub pages, you don't need these.
organizationName: 'ezinneanne', // Usually your GitHub org/user name.
projectName: 'docs-as-code-tutorial', // Usually your repo name.

你可以通过以下方式将站点部署到 GitHub Pages：

• 使用 PowerShell 终端，并运行命令：cmd /C 'set "GIT_USER=<你的用户名>" && yarn deploy'
• 使用 Windows 命令行终端，并运行命令：cmd /C "set "GIT_USER=<你的用户名>" && yarn deploy"
• 使用 Bash，并运行命令：GIT_USER=<你的用户名> yarn deploy

只需确保将 <你的用户名> 替换为你的 GitHub 用户名。瞧！站点已部署到 https://ezinneanne.github.io/docs-as-code-tutorial/。

部署在 GitHub Pages 上的文档即代码主页

使用 Netlify 部署

要部署到 Netlify，你只需要生产 URL 和基础 URL：

// Set the production url of your site here
url: 'https://docs-as-code-tutorial.netlify.app',
baseUrl: '/',

1. 前往你的 Netlify 账户（https://www.netlify.com/）并链接你的仓库。
2. 点击 Add new site。
3. 点击 import an existing project。
4. 连接到你的 GitHub 账户并选择 docs-as-code-tutorial 仓库。
5. 为你的站点命名，应与 docusaurus.config.js 中的 URL 相同。
6. 添加发布目录 build 和构建命令 npm run build。除非你另行指定，Netlify 将部署到你的默认分支 main。
7. 最后，部署！你应该会看到站点运行在 https://docs-as-code-tutorial.netlify.app/。

如需其他部署选项，你可以查看 Docusaurus 文档（https://docusaurus.io/docs/deployment）。

步骤 8：使用 GitHub Actions 设置文档工作流

现在我们将为文档设置一个工作流。在 GitHub 中，当你部署到 GitHub Pages 时，它会为你创建一个默认工作流，位于 pages-build-deployments。Netlify 也会自动部署，但不会在仓库中创建工作流文件。相反，它通过其平台管理流程，监视你的仓库更改并根据你的设置运行构建。

在本教程中，我们将使用 GitHub Actions 设置一个工作流，自动化运行 Vale 对文档执行 linting 检查。

创建一个 .github/workflows 目录，并在其中添加一个 vale-linter.yml 文件。在其中添加以下代码：

name: Vale Lint Checker

# Trigger the workflow on specific events.
on:
  push:
    # Run on every push to the main branch.
    branches:
      - main
  pull_request:
    # Run on pull requests targeting any branch.
    branches:
      - '*'
  workflow_dispatch:
    # Allow manual triggering from the Actions tab.

jobs:
  prose:
    runs-on: ubuntu-latest
    steps:
      # Step 1: Check out the repository code.
      - name: Checkout Code
        uses: actions/checkout@v3

      # Step 2: Set up Node.js
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16 # Use Node.js 16 or higher

      # Step 3: Run Vale lint checks.
      - name: Vale Lint
        uses: errata-ai/vale-action@reviewdog
        with:
          files: .
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

进行这些更改后，运行以下命令：

git add .
git commit -m "changes"

最后使用 git push 推送到仓库。转到仓库中的 Actions 选项卡。你应该会看到工作流正在运行：

GitHub 仓库页面，突出显示 Actions 选项卡，显示 vale 工作流

点击 changes 按钮，然后点击 prose 作业。

Vale 在 prose 作业运行中的 lint 输出预览

现在，你应该会看到所有 .md 文件中的行被 Vale 突出显示。这样，你的文档就可以像代码库一样运行了！你可以进行更改，推送、审查和合并后，它将自动同步。

请注意，这是针对 Netlify 的。对于 GitHub Pages，你还需要设置一个自动部署的工作流。

总结

在本教程中，你学习了如何使用 Docusaurus 设置文档即代码。你还了解了如何将文档部署到在线站点，以及如何使用 Vale 和 GitHub Actions 自动化 linting 工作流。

还有其他工作流（https://docs.github.com/en/actions/use-cases-and-examples/creating-an-example-workflow）可以帮助你减轻管理文档站点的工作负担。请记住，核心要点是使用软件开发工具来组织和结构化你的文档，同时自动化常规文档实践。这使你能够专注于最重要的事情：为读者创作高质量的内容。

免费学习编程。freeCodeCamp 的开源课程已经帮助超过 40,000 人获得了开发人员的工作。点击开始学习（https://www.freecodecamp.org/learn）