使用Docusaurus构建现代化文档网站

2025年2月19日 · 阅读需 38 分钟

翻译自：https://semaphoreci.com/blog/docusaurus?spm=5176.29680977.0.0.29b8PErsPErscX

在构建一个软件产品时，无论是一个框架、库，或者任何有趣的技术，拥有一个设计良好的文档网站，提供优秀的用户体验是必不可少的。不管产品本身有多出色，如果文档不到位，它可能严重影响该产品的采用和使用性。用户经常抱怨浪费时间寻找答案，不得不求助于外部资源，或对官方文档付出的努力微乎其微表达失望。

对于投入了无数时间构建产品的开发者或组织来说，这样的批评可能会令人沮丧，但它们突出了一个重要的现实：如果你的文档网站建设得很糟糕，它会给人留下产品质量差的坏印象。

然而，从头开始构建一个软件文档网站可能令人望而却步。这需要极大的努力和对细节的敏锐注意。使用像Next.js这样的通用工具无疑是一个可行的选择，但它需要手动处理内容管理、SEO、可访问性、版本控制以及其他技术复杂性方面的问题。处理这些复杂性可能会分散人们创建全面软件文档这一核心目标的注意力。

多年来，为了应对这些挑战，涌现出了多种专门工具。Docusaurus就是其中一个受到欢迎的工具。Docusaurus通过处理技术上的繁重工作，使得构建软件文档变得极为容易，让你能够更多地专注于创造高质量的内容，而不是担心底层的基础设施。在这篇文章中，我们将学习如何使用Docusaurus来构建既美观又实用、而且使用起来令人愉悦的文档。

Docusaurus是什么？

Docusaurus 是一个用于构建文档网站的开源工具。它由 Meta 的工程师们创建，目的是使创建和维护文档变成一种愉悦的体验。Docusaurus 背后的理念是允许您使用 Markdown 和基于 React 的 MDX 来编写文档。这种结合让创建常规文档页面和互动内容变得简单。Docusaurus 最大的优点之一是它建立在 React 之上，这意味着您可以利用现有的 React 知识并编写自定义 React 组件。包括 Algolia、Redis Labs Developer Site、Atlas、Jest 和 React Native 在内的许多知名公司，仅举几例，都因为它提供的卓越开发者体验而采用了 Docusaurus 来构建他们的文档。

为什么选择Docusaurus？与其他选择的比较

Docusaurus经常是构建文档网站的热门选择，但它并不是唯一可用的选项。让我们将Docusaurus与一些流行的替代品进行比较：

功能	Docusaurus	GitBook	MkDocs	VuePress	Jekyll	Sphinx
基础技术	React	JavaScript	Python	Vue	Ruby	Python
自定义性	高	中等	中等	高	高	高
学习曲线	中等	低	低	中等	中等	陡峭
版本控制	内置	有限	插件	插件	插件	内置
国际化	内置	内置	插件	插件	插件	内置
性能	高	中等	高	高	中等	高
MDX 支持	是	否	否	否	否	否
搜索功能	内置	内置	插件	插件	插件	内置
输出格式	网页	网页，PDF	网页	网页	网页	网页，PDF，ePub
最适用于	大型Web文档，React开发者	快速设置，非开发人员	中小项目	Vue开发者	静态站点	Python项目

每个工具都有其优势，但当你需要一个现代化、可定制的文档网站，并且拥有版本控制和国际化等开箱即用的功能时，Docusaurus表现尤为出色。其基于React的基础使它对那些已经在处理基于React的项目的团队格外吸引人。

先决条件

为了确保你能有效地跟上进度，本教程假设你具备以下条件：

Node.js已安装
React的基础知识
Markdown语法的基本理解

开始使用

Docusaurus 简化了设置文档网站的过程，使您能够快速从概念到部署。在本节中，我们将初始化一个新的 Docusaurus 项目，探索其结构，并使其在本地运行。

安装Docusaurus

Docusaurus 提供了一个实用的命令行工具，该工具使用合理的默认值来构建一个新项目。要初始化一个新项目，请打开你的终端并运行：

npx create-docusaurus@latest my-docs classic

这将创建一个名为 my-docs 的新Docusaurus项目，但您可以使用任何您喜欢的名字。classic 标志指定该项目将使用经典模板，其中包括文档站点所需的基本功能和配置。在设置过程中，您将被提示选择：

Javascript或者Typescript（为了本教程的目的，我将使用Javascript）
可选的 GitLab/GitHub 仓库创建

您也可以从一开始就选择使用任何包管理器，比如npm、yarn或pnpm。

npm init docusaurus
# or
yarn init docusaurus
# or
pnpm init docusaurus

项目结构

让我们进入新创建的Docusaurus项目，并熟悉其结构：

cd my-docs

你会看到类似于：

my-docs
├── blog
├── docs
│   ├── intro.md
│   └── tutorial-basics
│       ├── congratulations.md
│       ├── create-a-blog-post.md
│       ├── create-a-document.md
│       ├── create-a-page.md
│       ├── deploy-your-site.md
│       ├── markdown-features.md
│       └── thank-you.md
├── package.json
├── src
│   ├── components
│   ├── css
│   └── pages
├── static
├── .gitignore
├── barbel.config.js
├── package.json
├── package-lock.json
└── docusaurus.config.js

关键目录：

blog/：这个目录包含用 Markdown 或 mdx 编写的博客文章。
docs/：这是一个放置文档文件的位置，文件格式为Markdown或mdx。
src/：在这里，你可以创建页面和自定义组件、布局以及其他与你的网站相关的React代码。
static/：这个目录用于存放静态资源，如图片、字体等。
docusaurus.config.js：这是您的Docusaurus站点的主要配置文件。
sidebars.js：文件负责自动生成和自定义侧边栏。

在本地运行

首先，运行 npm install 来安装所有所需的依赖项，然后启动你的开发服务器：

npm run start

这将编译所有Markdown和React文件，启动一个本地开发服务器（通常位于http://localhost:3000），并启用热重载以便立即更新。你应该可以在浏览器中看到默认的Docusaurus站点正在运行。

理解配置文件

我们将从探索docusaurus.config.js文件开始。这个文件作为你的Docusaurus项目的控制中心，你可以通过它调整站点的行为、外观和功能。让我们解析这个配置文件，并理解每一部分如何塑造你的文档的身份和用户体验。

在你的编辑器中打开docusaurus.config.js。你会看到如下结构：

const config = {
  title: "My Site",
  tagline: "Dinosaurs are cool",
  favicon: "img/favicon.ico",
  url: "https://your-docusaurus-site.example.com",
  baseUrl: "/",
  organizationName: "facebook",
  projectName: "docusaurus",
  onBrokenLinks: "throw",
  onBrokenMarkdownLinks: "warn",
  i18n: {
    defaultLocale: "en",
    locales: ["en"],
  },
  //...
};

export default config;

核心字段：

title：你的Docusaurus网站的标题。
tagline：您网站的简短标语或描述。
favicon：你的网站的favicon图标的路径。
url：您的网站将托管的URL地址。
baseUrl：您网站的基础URL路径（通常是/）。
organizationName 和 projectName：这些用于 Docusaurus 的某些特性，比如编辑按钮。
onBrokenLinks 和 onBrokenMarkdownLinks：这些控制Docusaurus如何处理损坏的链接。
i18n：该对象配置国际化（i18n）设置，如默认区域设置和支持的区域设置。

主题配置

themeConfig对象用于定义网站的外观和感觉。

const config = {
  //...
  themeConfig: {
    image: "img/docusaurus-social-card.jpg",
    navbar: {
      title: "My Site",
      logo: {
        alt: "My Site Logo",
        src: "img/logo.svg",
      },
      items: [
        {
          type: "docSidebar",
          sidebarId: "tutorialSidebar",
          position: "left",
          label: "Tutorial",
        },
        { to: "/blog", label: "Blog", position: "left" },
        {
          href: "https://github.com/facebook/docusaurus",
          label: "GitHub",
          position: "right",
        },
      ],
    },
    footer: {
      style: "dark",
      links: [
        {
          title: "Docs",
          items: [
            {
              label: "Tutorial",
              to: "/docs/intro",
            },
          ],
        },
        {
          title: "Community",
          items: [
            {
              label: "Stack Overflow",
              href: "https://stackoverflow.com/questions/tagged/docusaurus",
            },
            {
              label: "Discord",
              href: "https://discordapp.com/invite/docusaurus",
            },
            {
              label: "Twitter",
              href: "https://twitter.com/docusaurus",
            },
          ],
        },
        {
          title: "More",
          items: [
            {
              label: "Blog",
              to: "/blog",
            },
            {
              label: "GitHub",
              href: "https://github.com/facebook/docusaurus",
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
  //...
};

navbar：定义 logo、标题和导航项。
footer：设置样式、链接和版权声明。
prism：选择一个语法高亮主题。

预设和主题

Docusaurus 使用预设来打包插件和主题：

const config = {
  //...
  presets: [
    [
      "classic",
      {
        docs: {
          sidebarPath: "./sidebars.js",
          editUrl: "link/to/edit/page",
        },
        blog: {
          showReadingTime: true,
          editUrl: "link/to/edit/page",
        },
        theme: {
          customCss: "./src/css/custom.css",
        },
      },
    ],
  ],
  //...
};

docs：设置路径和侧边栏配置。
blog：配置博客功能。
theme：应用自定义CSS以进行精细调整的样式。

这是对docusaurus.config.js文件的快速概述。这个文件的优点是，你可以通过修改它来自定义你的文档的各种方面，而无需触及其他文件或编写额外的代码。例如，如果你更改title和tagline为其他内容，它将更新首页和其他使用这些值的部分。以下示例演示了这一点：

const config = {
  title: "Semaphore",
  tagline: "Build, Test, Deploy - At Lightning Speed",
  //...
};

这将更新首页的 title 和 tagline，无需直接修改 src/pages/index.js。

创建页面

Docusaurus允许您在src/pages目录中创建独立页面。这些页面与文档页面不同，可用于自定义内容，诸如主页、关于页面或您需要的任何其他静态内容。要创建一个新页面，请导航到src/pages文件夹。例如，如果您需要创建一个关于页面，您将在该文件夹内创建about.jsx文件。

touch src/pages/about.jsx

向about.jsx文件添加内容：

import React from "react";
import Layout from "@theme/Layout";

function About() {
  return (
    <Layout title="About Us">
      <div style={{ padding: "20px" }}>
        <h1>About Us</h1>
        <p>
          Semaphore CI is a cloud-based continuous integration and delivery platform that accelerates software development. We help teams build test, and deploy code faster and more reliably.
        </p>
      </div>
    </Layout>
  );
}

export default About;

现在访问：http://localhost:3000/about

这段代码定义了一个简单的关于页面的React组件。来自Docusaurus的layout组件提供了网站的头部、尾部和其他布局特性。虽然使用Javascript/JSX创建页面很方便，你也可以选择使用Markdown或React MDX。

将页面添加到导航栏

要想通过导航栏访问 about 页面，你需要更新根目录中的 docusaurus.config.js 文件。

const config = {
  //...
  themeConfig: {
    image: "img/docusaurus-social-card.jpg",
    navbar: {
      title: "My Site",
      logo: {
        alt: "My Site Logo",
        src: "img/logo.svg",
      },
      items: [
        {
          type: "docSidebar",
          sidebarId: "tutorialSidebar",
          position: "left",
          label: "Tutorial",
        },
        { to: "/blog", label: "Blog", position: "left" },
        // Add new Navlink here
        { to: "about", label: "About", position: "left" },
        {
          href: "https://github.com/facebook/docusaurus",
          label: "GitHub",
          position: "right",
        },
      ],
    },
    //...
  },
  //...
};

这个配置在导航栏中添加了一个指向关于页面的链接。检查浏览器以查看更改。

创建文档页面

在Docusaurus中，文档内容通常位于项目的docs目录中。让我们通过删除docs文件夹中的默认文件来开始新的操作。接下来，我们将把导航栏中的Tutorial项重命名为Docs，以更好地代表一个真实的文档网站。打开docusaurus.config.js文件并找到themeConfig.navbar.items部分。更新docSidebar项的标签字段，从Tutorial改为Docs：

const config = {
  themeConfig: {
    navbar: {
      items: [
        // ...
        {
          type: "docSidebar",
          sidebarId: "tutorialSidebar",
          position: "left",
          label: "Docs",
        },
        // ...
      ],
    },
  },
};

要创建一个新的文档页面，请确保您位于 docs 文件夹中。创建一个新的 Markdown 或 React MDX 文件。以这个例子来说，我们创建一个名为 welcome.mdx 的文件：

touch docs/welcome.mdx

在你的文本编辑器中打开 welcome.mdx 文件，并添加以下内容：

---
id: welcome
title: 欢迎
description: 这是欢迎页面的描述
slug: /welcome
---

# 欢迎来到我的文档

这是我在Docusaurus中的第一个文档页面。

新的 welcome 页面链接将出现在文档的侧边栏中。您也可以在浏览器中导航至 localhost:3000/docs/welcome 来访问该页面。

docusaurus

理解文档页面的结构

Docusaurus 文档页面由两个主要部分组成：

前言部分：被三个破折号（---）所包围的顶部区域。它包含了元数据，如独特的id、title（标题）、description（描述）、slug（固定链接）以及关于页面的其他细节。这些元数据指导了Docusaurus如何生成侧边栏、页面标题、URL等。就像HTML中的<head>部分一样。这些元数据在渲染后的文档页面中是不可见的，但是被Docusaurus用来生成侧边导航栏、页面标题、URL和其他功能。
主要内容：这里您可以使用Markdown语法撰写实际文档。在这里，您可以通过标题、代码块、图像来构建内容，并充分利用Markdown的表现力。

自定义文档页面

您可以使用各种前置字段自定义文档页面的行为和外观。例如，要更改侧边栏中页面的顺序，您可以使用 sidebar_position 字段：

---
id: welcome
title: 欢迎
description: 这是欢迎页面的描述
slug: /welcome
sidebar_position: 1
---

# 你的 Markdown 内容放在这里

设置 sidebar_position: 1 将会把页面移动到侧边栏的第一个位置。其他接受的前言字段包括：

sidebar_label: 这份文档在侧边栏导航中显示的标签。
hide_title：一个布尔标志位，用来隐藏文档页面顶部的标题。
pagination_label: 文档页面底部的分页导航标签。
custom_edit_url：自定义“编辑此页面”链接的 URL。
keywords：与文档相关的关键词数组，用于搜索引擎优化。
image: 文档的预览图或社交媒体缩略图可以使用的相对路径或URL。
hide_table_of_contents：一个布尔标志，用于隐藏该文档的目录。
toc_min_heading_level`：一个整数值（1-6），它指定要在目录中包含的最小标题级别。
toc_max_heading_level: 指定要包含在目录中的最大标题级别的整数值（1-6）。
pagination_next: “下一页”分页链接的标签。
pagination_prev: “上一页”分页链接的标签。

分组文档页面

在Docusaurus中，您可以通过在docs目录内创建一个子文件夹来对页面进行分组。假设您想创建一个包含“安装”和“集成”页面的“入门”类别。首先，在docs目录中创建子文件夹：

mkdir docs/getting-started

在getting-started文件夹内创建一个名为_category_.json的JSON文件。这个文件定义了类别的侧边导航结构。添加如下内容：

{
  "label": "Getting Started",
  "position": 1,
  "link": {
    "type": "generated-index"
  }
}

label 指定了类别名，而 position 决定了它在侧边栏中的顺序。link 字段为该类别创建了一个索引页面，列出了其所有页面。

将页面添加到分类

接下来，为这个类别创建页面：

touch docs/getting-started/installation.md docs/getting-started/integration.md

在installation.md页面添加适当的前言内容：

---
id: installation
title: Installation
sidebar_position: 1
---

# Installation

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

向integration.md中添加内容：

---
id: integration
title: Integration
sidebar_position: 2
---

# Integration

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

现在，这些页面将会被归纳到侧边栏的“入门”类别下，并且索引页将会列出它们。

在Docusaurus中使用React

Docusaurus 允许你直接在文档页面中嵌入 React 组件，这为你创建互动和动态内容提供了灵活性。这得益于 MDX（带有 JSX 的 Markdown），它允许你在 Markdown 文件中使用 JSX。这个功能在你想展示实时示例、抽象出重复代码或者为你的文档增加复杂交互性时特别有用。要在文档页面中使用 React 组件，保证你的文档文件格式是 .mdx 而不是 .md。在这个示例中，我们将创建一个名为 ColorBox 的基础组件。在项目的根目录中，导航到 src/components 文件夹（如果它不存在则创建它），然后创建一个 .js 或 .jsx 组件：

mkdir -p src/components
touch src/components/ColorBox.jsx

向文件中添加内容：

import React from 'react';

const ColorBox = ({ color }) => (
  <div 
    style={{
      backgroundColor: color,
      width: '100px',
      height: '100px',
      display: 'inline-block',
      margin: '10px'
    }}
  />
);

export default ColorBox;

您可以在 MDX 文件中使用这个组件。以下例子使用之前创建的 welcome.mdx 文件来进行演示：

---
id: welcome
title: 欢迎
description: 这是欢迎页面的描述
slug: /welcome
---

import ColorBox from '@site/src/components/ColorBox';

# 欢迎来到我的文档
这是我在Docusaurus中的第一篇文档页面。

<ColorBox color="red" />
<ColorBox color="blue" />
<ColorBox color="green" />

注：在import语句中的@site别名是Docusaurus中的一个特殊路径别名，它指向你的项目根目录。

在浏览器中，你应该会看到自定义组件随着Markdown内容一起渲染出来：

docusaurus

这种方法使您能够创建丰富且互动的文档，超越了静态文本和图像。您可以在文档页面中直接嵌入实时代码编辑器、交互式图表甚至小型应用程序。

专业提示：虽然React组件可以极大地提升你的文档质量，但要谨慎使用。对于简单的内容，简单的Markdown经常更易于维护且性能更好。将React组件保留给交互元素或复杂的视觉效果，这些是标准Markdown无法实现的。

版本控制文档

Docusaurus具有内置的文档版本控制支持，它允许您维护文档的多个版本，并向用户提供特定版本的内容。要启用版本控制，您首先需要配置您的Docusaurus项目以支持它。

打开 docusaurus.config.js 并更新它以包括版本设置。在配置文件的 docs 字段中添加以下内容：

const config = {
  //...
  presets: [
    [
      "classic",
      {
        docs: {
          // ....
          lastVersion: "current",
          versions: {
            current: {
              label: "Next",
              path: "next",
            },
          },
        },
        //...
      },
    ],
  ],
  //...
};

这个配置通过Next版本来设置版本控制，这是当前文档版本的默认标签。

要创建你的文档的初始版本，请运行以下命令：

npm run docusaurus docs:version 1.0.0

这将在新的 versioned_docs 目录内创建一个 version-1.0.0 目录，并在项目目录中创建一个 versions.json 文件。你应该有如下的文件夹结构：

my-docs/
├── docs/
│   └── ... # 当前文档文件
├── versioned_docs/
│   └── version-1.0.0/
│       └── ... # 为版本1.0.0复制的文档文件
├── versions.json # 版本控制的元数据文件
├── ...

创建新版本

要添加更多版本的文档，请使用新的版本号运行docs:version命令：

npm run docusaurus docs:version 1.1.0

这将在versioned_docs文件夹内创建一个名为version-1.1.0的新目录，并将docs目录中的文档文件复制到其中。新版本还会被添加到versions.json文件中。创建新版本后，您应该会看到更新后的文件夹结构如下：

my-docs/
├── docs/
│   └── ... # 当前文档文件
├── versioned_docs/
│   ├── version-1.0.0/
│   │   └── ... # 1.0.0版本的文档文件
│   └── version-1.1.0/
│       └── ... # 1.1.0版本的文档文件
├── versions.json
├── ...

你可以继续更新docs目录中的文档文件，当你准备创建一个新的版本时，只需要再次运行docusaurus的docs:version命令，并附上新的版本号即可。

管理版本

根目录中的versions.json文件包含有关您文档不同版本的元数据。它看起来像这样：

["1.0.0", "1.1.0"]

您可以手动编辑这个文件来按需添加或删除版本。

在导航栏中添加版本下拉菜单

设置版本控制之后，您可以更新 docusaurus.config.js 中的导航栏以显示版本下拉菜单。打开配置文件，在 config.themeConfig.items 中添加以下内容：

const config = {
  //...
  themeConfig: {
    //...
    items: [
      // ...
      {
        type: "docsVersionDropdown",
        position: "right",
      },
    ],
  },
  //...
};

这将在导航栏中显示一个版本下拉菜单。

docusaurus

专业提示：如果你的文档很少更改，版本控制可能引入不必要的复杂性。在大多数情况下，维护一份最新的文档版本更为简单且更有效。

探索插件

Docusaurus 拥有一个兴旺的插件生态系统，这些插件可以扩展你的文档网站的功能。让我们来看一个在 Docusaurus 中集成翻译和国际化插件的例子。

翻译和国际化

Docusaurus内置了对国际化（i18n）的支持，允许您创建多语言文档网站。这个功能让您能够通过提供多种语言的翻译内容，接触全球观众。让我们在Docusaurus项目中设置和管理翻译。

配置区域设置

第一步是配置你希望你的文档网站支持的语言环境（语言）。打开 docusaurus.config.js 文件并找到 i18n 对象。默认情况下，它应该是这样的：

i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },

要添加一种新的地区设置，例如法语（fr），更新地区设置数组：

i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
  },

翻译内容

在配置好区域设置后，你可以开始翻译你的内容。Docusaurus 期望将翻译放置在 project-root/i18n 文件夹内的特定目录结构中。在根文件夹中创建一个名为 i18n 的目录：

mkdir -p i18n

Docusaurus提供了一个命令行工具，您可以使用它来管理翻译。要从Markdown文档和React组件中提取可翻译的内容，请运行以下命令。

npm run write-translations

这个命令默认只会在i18n目录下生成英语（en）区域目录和可翻译的JSON文件。要指示命令生成法语区域或您指定的区域，您必须通过提供--locale标志来指定。例如，要生成法语（fr）区域，请运行：

npm run write-translations -- --locale fr

这将在i18n目录内生成一个包含可翻译文件的fr语言区域目录。你应该拥有如下的文件夹结构：

my-docs/
└── i18n
    ├── en
    │   ├── code.json
    │   ├── docusaurus-plugin-content-blog
    │   │   └── options.json
    │   ├── docusaurus-plugin-content-docs
    │   │   ├── current.json
    │   │   ├── version-1.0.0.json
    │   │   └── version-1.1.0.json
    │   └── docusaurus-theme-classic
    │       ├── footer.json
    │       └── navbar.json
    ├── fr
    │   ├── code.json
    │   ├── docusaurus-plugin-content-blog
    │   │   └── options.json
    │   ├── docusaurus-plugin-content-docs
    │   │   ├── current
    │   │   │   ├── version-1.0.0
    │   │   ├── current.json
    │   │   ├── version-1.0.0.json
    │   │   └── version-1.1.0.json
    │   └── docusaurus-theme-classic
    │       ├── footer.json
    │       └── navbar.json
  //....

在locale的每个JSON文件代表了你的文档中的一个特定方面，你可以在其中手动翻译内容。例如，current.json文件负责翻译一般文本内容和UI元素，如网站的title（标题）、description（描述）和主题labels（标签）。而在i18n/fr/docusaurus-theme-classic目录下的navbar.json和footer.json分别负责翻译navbar（导航栏）和footer（页脚）的内容到法语。你可以浏览所有的JSON文件，并翻译尽可能多的方面，从而创建一个完全本地化的文档网站。

要翻译你的文档内容，你需要将文档内容从 docs 文件夹复制到 i18n/fr/docusaurus-plugin-content-docs/current/ 中。复制 docs 目录内的所有文件：

mkdir -p i18n/fr/docusaurus-plugin-content-docs/current
cp -r docs/* i18n/fr/docusaurus-plugin-content-docs/current/

复制之后，你需要手动将内容翻译成你所希望的语言，在这个例子中是法语。多语言设置的结构应该看起来是这样的：

my-docs/
└── i18n
    ├── en
    │   ├── code.json
    │   ├── docusaurus-plugin-content-blog
    │   │   └── options.json
    │   ├── docusaurus-plugin-content-docs
    │   │   ├── current.json
    │   │   ├── version-1.0.0.json
    │   │   └── version-1.1.0.json
    │   └── docusaurus-theme-classic
    │       ├── footer.json
    │       └── navbar.json
    ├── fr
    │   ├── code.json
    │   ├── docusaurus-plugin-content-blog
    │   │   └── options.json
    │   ├── docusaurus-plugin-content-docs
    │   │   ├── current
    │   │   │   ├── getting-started
    │   │   │   │   ├── installation.md
    │   │   │   │   ├── integration.md
    │   │   │   ├── welcome.mdx
    │   │   │   ├── version-1.0.0
    │   │   ├── current.json
    │   │   ├── version-1.0.0.json
    │   │   └── version-1.1.0.json
    │   └── docusaurus-theme-classic
    │       ├── footer.json
    │       └── navbar.json

要使翻译生效，您需要重启服务器并添加 --locale 标志。

npm run start -- --locale fr

现在，当你刷新浏览器时，在访问localhost:3000/fr/docs/next/welcome时你应该会看到类似这样的内容：

docusaurus

启用语言下拉菜单

配置了区域设置并提供了翻译之后，您可以在站点的导航栏中启用语言下拉菜单。打开 docusaurus.config.js 文件并找到 themeConfig.navbar.items 数组。添加以下条目：

const config = {
  themeConfig: {
    navbar: {
      items: [
        // ...
        {
          type: "localeDropdown",
          position: "right",
        },
      ],
    },
  },
};

这将在导航栏的右侧添加一个语言下拉菜单，允许用户在已配置的区域设置之间切换。

路由和URL结构

注意：国际化在开发环境与生产环境中的工作方式略有不同。在生产环境中，您可以无缝切换所提供的语言，而不会遇到任何问题。然而，在开发环境中，您需要在启动服务器时指定区域设置，并且一次只支持一种语言。这意味着，如果您在法语区域设置中启动开发服务器，然后切换到比如英语，您将会收到一个404错误。在生产环境中，这将不是问题，因为Docusaurus会自动处理译文的路由和URL结构。当用户从语言下拉菜单中选择不同的区域设置时，Docusaurus将加载相应的翻译内容，并更新URL以反映所选的区域设置。例如，如果用户访问英文网站(en)的/docs/welcome URL，然后切换到法语(fr)区域设置，Docusaurus将加载welcome.mdx文件的法语翻译，并将URL更新为/fr/docs/welcome。

关于插件的更多信息

早些时候，我们学习了如何利用定位插件，但这只是插件可以为您的Docusaurus站点做的事情的一小部分。有大量有用的插件可以使事情变得更容易。假设您需要将Google Analytics集成到您的项目中。方法如下：

安装插件

首先，通过运行这个命令来安装所需的插件：

npm install --save @docusaurus/plugin-google-gtag

插件安装后，您可以在docusaurus.config.js文件中对其进行配置。查找预设数组并找到presets条目。然后在其中添加这个gtag配置：

const config = {
  //...
  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      
      ({
         gtag: {
          trackingID: 'G-999X9XX9XX', 
          anonymizeIP: true,
        },
        docs: {
          sidebarPath: './sidebars.js',
          lastVersion: 'current',
          versions: {
            current: {
              label: 'Next',
              path: 'next',
            },
          },
        },
        //...
      }),
    ],
  ],
  //...
};

请确保将 G-999X9XX9XX 替换为您实际的谷歌分析跟踪ID。anonymizeIP 选项通过在发送数据前匿名处理访问者IP地址来帮助保护隐私。谷歌标签在开发环境中被禁用。这种行为是故意的，以防止在您本地开发和测试网站时发送不必要的分析数据。谷歌标签将在生产环境中启用，您的网站应该能够收集分析数据。您可以使用 tagassistant.google 确认您的谷歌分析实施是否使用您的生产链接正确工作。

您可以从Docusaurus官方网站探索更多插件，以扩展您的文档网站的功能性和能力。

部署你的 Docusaurus 网站

在构建了你的文档网站之后，没有什么比看到它实际上线和运行更令人满意的了。Docusaurus 提供了一个命令行界面（CLI）来简化部署流程，使该过程变得直接明了。你还可以将你的站点部署到像 Vercel 或 Netlify 这样的云服务上，它们提供了额外的特性和便利性。

使用Docusaurus CLI进行部署

Docusaurus 包含一个内置的命令行工具，可以简化部署过程。使用 Docusaurus CLI 部署你的网站：

确保你的网站已构建并准备好部署。运行以下命令以创建一个适合生产的构建：

npm run build

这将在build目录中生成静态文件，这些文件可以由任何静态网站托管服务来提供。

为了确保一切按预期工作，请通过运行以下命令在本地测试您的构建：

npm run serve

这将启动一个本地服务器，您可以通过导航到提供的URL查看您的网站。确保检查所有页面和功能，以验证它们是否正常工作。

部署到云服务

为了更高的灵活性，可以将你的Docusaurus站点部署到像Vercel或Netlify这样的云服务上，它们提供了与Git的无缝集成和自动化部署工作流。请跟随它们的设置指南进行操作。

部署到Vercel
部署到Netlify

专业提示：修复你的Docusaurus项目中的断链，以防止部署失败。

在本教程的前面部分，我们删除了docs目录中的所有默认文件和文件夹。这可能导致了链接断裂，特别是那些指向docs/intro的引用。为了确保部署顺利进行：

打开 docusaurus.config.js文件
导航到 `config.themeConfig.footer.links.items
删除或替换 /docs/intro 为一个有效链接，或者使用相对路径 /。

const config = {
  //...
  themeConfig: {
    footer: {
      style: "dark",
      links: [
        {
          title: "Docs",
          items: [
            {
              label: "Tutorial",
              to: "/docs/intro", // Resolve this broken link
            },
          ],
        },
        //...
      ],
    },
  },
  //...
};

重复此过程，针对 src/pages/index.js 文件，更新任何类似的引用。

总结

我们在本指南中覆盖了很多内容。我们涉及了初始化新的Docusaurus项目、创建文档、版本控制、集成插件、部署Docusaurus网站等关键概念。构建文档网站并非简单任务，但Docusaurus之类的工具通过提供流线型工作流程和开箱即用的核心特性，将许多复杂性从方程中去除了。虽然本指南旨在提供坚实的基础，但Docusaurus仍有更多可以探索的内容。通过Docusaurus广泛的插件和主题生态系统，有无限的自定义可能性。

请随意克隆我的工作仓库，在这里并行操作新的、逐步提供的教程。如果有任何问题/需要澄清的地方或者发现了bug，请随时联系我！

Docusaurus是什么？​

为什么选择Docusaurus？与其他选择的比较​

先决条件​

开始使用​

安装Docusaurus​

项目结构​

在本地运行​

理解配置文件​

核心字段：​

主题配置​

预设和主题​

创建页面​

将页面添加到导航栏​

创建文档页面​

理解文档页面的结构​

自定义文档页面​

分组文档页面​

将页面添加到分类​

在Docusaurus中使用React​

版本控制文档​

创建新版本​

管理版本​

在导航栏中添加版本下拉菜单​

探索插件​

翻译和国际化​

配置区域设置​

翻译内容​

启用语言下拉菜单​

路由和URL结构​

关于插件的更多信息​

安装插件​

部署你的 Docusaurus 网站​

使用Docusaurus CLI进行部署​

部署到云服务​

专业提示：修复你的Docusaurus项目中的断链，以防止部署失败。​

总结​

Docusaurus是什么？

为什么选择Docusaurus？与其他选择的比较

先决条件

开始使用

安装Docusaurus

项目结构

在本地运行

理解配置文件

核心字段：

主题配置

预设和主题

创建页面

将页面添加到导航栏

创建文档页面

理解文档页面的结构

自定义文档页面

分组文档页面

将页面添加到分类

在Docusaurus中使用React

版本控制文档

创建新版本

管理版本

在导航栏中添加版本下拉菜单

探索插件

翻译和国际化

配置区域设置

翻译内容

启用语言下拉菜单

路由和URL结构

关于插件的更多信息

安装插件

部署你的 Docusaurus 网站

使用Docusaurus CLI进行部署

部署到云服务

专业提示：修复你的Docusaurus项目中的断链，以防止部署失败。

总结