跳转至主内容
Version: 2.0.0-beta.20

安装

Docusaurus 本质上是一组 npm 包的集合.

tip

使用快速通道以在 5 分钟 ⏱内了解 Docusaurus！

直接访问 docusaurus.new 来体验 Docusaurus 运行示例！

需求​

  • Node.js v14.13或以上版本 (可以运行 node -v 命令查询版本号)。 您可以使用 nvm 来管理同一机器上的多个 Node 版本。
    • 安装 Node.js 时，建议检查与依赖相关的所有复选框。

项目脚手架​

使用命令行工具可帮助您快速简单地安装 Docusaurus 并搭建脚手架网站。 您可在空仓库或现有仓库的任意处运行此命令，它将会创建内含模板文件的新目录。

npx [email protected] my-website classic

推荐使用 classic 模板来快速开始，同时它也包含 Docusaurus 1 中的特性。 classic 模板内有 @docusaurus/preset-classic 软件包，其包含了标准文档、博客、自定义页面及 CSS 框架 (支持暗色模式)。 您可以使用此经典模板来快速设立网站。当您熟悉了 Docusaurus 之后，您可以在之后对其自定义。

You can also use the template's TypeScript variant by passing the --typescript flag. 更多详情请查看Typescript支持

npx [email protected] my-website classic --typescript
FB-Only

If you are setting up a new Docusaurus website for a Facebook open source project, use the facebook template instead, which comes with some useful Facebook-specific defaults:

npx [email protected] my-website facebook
Alternative installation commands

You can also initialize a new project using your preferred project manager:

npm init docusaurus

运行 npx [email protected] --help ，或者查看 API文档以了解所有可用flag选项的更多信息

项目结构​

假设您选择了经典模板并将网站命名为 my-website，您将会在新目录 my-website/ 下看到下列文件：

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

解释项目结构​

  • /blog/ - 包含博客的 Markdown 文件。 如果您已经禁用了博客插件，您可以删除相关目录，或者您也可以在设置 path 选项之后修改其名称。 详情可参考 博客指南
  • /docs/ - 包含文档的 Markdown 文件。 您可在 sidebars.js 中自定义文档的侧边栏顺序。 如果您已经禁用了文档插件，您可以删除相关目录；或者您也可以在设置 path 选项之后修改此名称。 More details can be found in the docs guide
  • /src/ - 如页面或自定义 React 组件一类的非文档文件。 严格来说，您不一定要将非文档类文件放于此处。不过将它们放在一个集中的目录，可以让代码检查或者处理更为简便。
    • /src/pages - 所有放在此目录中的 JSX/TSX/MDX w文件都会被转换成网站页面。 您可在页面指南中了解详情
  • /static/ - 静态目录。 此处的所有内容都将被复制进 build 文件夹的根目录中
  • /docusaurus.config.js - 站点配置文件。 其等效于 Docusaurus 1 中的 siteConfig.js 文件
  • /package.json - Docusaurus 网站是一款 React 应用程序。 您可以安装并使用任何 npm 软件包
  • /sidebars.js - 由文档使用，用于指定侧边栏中的文档顺序

多代码库​

If you are using Docusaurus for documentation of an existing project, a monorepo may be the solution for you. Monorepos allow you to share dependencies between similar projects. For example, your website may use your local packages to showcase the latest features, instead of depending on a released version; your contributors can also conveniently update the docs as they implement features. An example monorepo folder structure is below:

my-monorepo
├── package-a # Another package, your actual project
│   ├── src
│   └── package.json # Package A's dependencies
├── website   # Docusaurus root
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies

In this case, you should run npx create-docusaurus within the ./my-monorepo folder.

If you're using a hosting provider such as Netlify or Vercel, you will need to change the Base directory of the site to where your Docusaurus root is. In this case, that would be ./website. Read more about configuring ignore commands in the deployment docs.

Read more about monorepos in the Yarn documentation (Yarn is not the only way to set up a monorepo, but it's a common solution), or checkout Docusaurus and Jest for some real-world examples.

运行开发服务器​

To preview your changes as you edit the files, you can run a local development server that will serve your website and reflect the latest changes.

cd my-website
npm run start

默认情况下，浏览器将自动打开 http://localhost:3000 的新窗口。

恭喜！ 您已成功创建了您的首个 Docusaurus 站点！ 来四处逛逛看看有什么功能吧！

构建​

Docusaurus 是一款现代化的静态网页生成器。因此，我们需要将网站生成为静态内容并上传至网页服务器以供访问。 要构建站点，请使用以下命令：

npm run build

网站内容将构建至 /build 目录，其随后可复制进如 GitHub Pages、Vercel 或 Netlify 一类的静态网页托管服务。 请查看部署流程了解详情。

更新 Docusaurus​

有多种途径更新您的 Docusaurus 版本。 其中一种稳定的方法是透过更改 package.json 中的版本号至指定版本。 请注意，所有以 @docusaurus/ 为命名空间的软件包都应使用同一版本。

package.json
{
  "dependencies": {
    "@docusaurus/core": "2.0.0-beta.20",
    "@docusaurus/preset-classic": "2.0.0-beta.20",
    // ...
  }
}

随后，在包含 package.json 的项目文件夹中，请运行软件包安装命令：

npm install

要检查是否成功更新，请运行：

npx docusaurus --version

您应能看到正确的版本输出。

若您使用 Yarn，您可使用如下命令：

yarn upgrade @docusaurus/[email protected] @docusaurus/[email protected]
tip

Use new unreleased features of Docusaurus with the @canary npm dist tag

遇到问题？​

Ask for help on Stack Overflow, on our GitHub repository, our Discord server, or Twitter.