跳转至主内容
版本: 2.0.0-beta.18

安装

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

tip

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

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

需求

  • Node.js 版本 >= 14 或以上 (可通过运行命令 node -v 查看版本). 您可以使用 nvm 来管理同一机器上的多个 Node 版本。
    • When installing Node.js, you are recommended to check all checkboxes related to dependencies.

项目脚手架

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

npx create-docusaurus@latest [name] [template]

示例:

npx create-docusaurus@latest website classic

若您不指定 nametemplate,它将会提示您补充。

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

template 选项还接收 git 仓库 URL 或本地文件路径,本地文件路径会以当前目录为起始路径。 Git 仓库或指定文件目录中的内容会复制到站点目录。 If it's a git repository, you can also specify a cloning strategy.

You can also use the template's TypeScript variant by passing the --typescript flag.

npx create-docusaurus@latest 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 create-docusaurus@latest my-website facebook
Alternative installation commands

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

npm init docusaurus
Docusaurus makes best efforts to select a package manager to install dependencies for you, based on the command you are using and the project you are in. You can override this behavior by using `--package-manager [npm/yarn/pnpm]`.
# Use Yarn to install dependencies even when the command is npx
npx create-docusaurus@latest my-website classic --package-manager yarn

Run npx create-docusaurus@latest --help for more information about all available flags.

项目结构

假设您选择了经典模板并将网站命名为 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 文件。 You can delete the directory if you've disabled the blog plugin, or you can change its name after setting the path option. 详情可参考 博客指南
  • /docs/ - 包含文档的 Markdown 文件。 您可在 sidebars.js 中自定义文档的侧边栏顺序。 You can delete the directory if you've disabled the docs plugin, or you can change its name after setting the path option. 您可在文档指南中了解详情
  • /src/ - 如页面或自定义 React 组件一类的非文档文件。 You don't have to strictly put your non-documentation files here, but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
    • /src/pages - Any JSX/TSX/MDX file within this directory will be converted into a website page. 您可在页面指南中了解详情
  • /static/ - 静态目录。 此处的所有内容都将被复制进 build 文件夹的根目录中
  • /docusaurus.config.js - 站点配置文件。 其等效于 Docusaurus 1 中的 siteConfig.js 文件
  • /package.json - Docusaurus 网站是一款 React 应用程序。 您可以安装并使用任何 npm 软件包
  • /sidebars.js - Used by the documentation to specify the order of documents in the sidebar

Monorepos

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 PagesVercelNetlify 一类的静态网页托管服务。 请查看部署流程了解详情。

更新 Docusaurus

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

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

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

npm install

要检查是否成功更新,请运行:

npx docusaurus --version

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

若您使用 Yarn,您可使用如下命令:

yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
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.