安装
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
- yarn
- pnpm
npm init docusaurus
yarn create docusaurus
pnpm create 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.
- npm
- Yarn
cd my-website
npm run start
cd my-website
yarn run start
默认情况下,浏览器将自动打开 http://localhost:3000 的新窗口。
恭喜! 您已成功创建了您的首个 Docusaurus 站点! 来四处逛逛看看有什么功能吧!
构建
Docusaurus 是一款现代化的静态网页生成器。因此,我们需要将网站生成为静态内容并上传至网页服务器以供访问。 要构建站点,请使用以下命令:
- npm
- Yarn
npm run build
yarn run build
网站内容将构建至 /build
目录,其随后可复制进如 GitHub Pages、Vercel 或 Netlify 一类的静态网页托管服务。 请查看部署流程了解详情。
更新 Docusaurus
有多种途径更新您的 Docusaurus 版本。 其中一种稳定的方法是透过更改 package.json
中的版本号至指定版本。 请注意,所有以 @docusaurus/
为命名空间的软件包都应使用同一版本。
{
"dependencies": {
"@docusaurus/core": "2.0.0-beta.20",
"@docusaurus/preset-classic": "2.0.0-beta.20",
// ...
}
}
随后,在包含 package.json
的项目文件夹中,请运行软件包安装命令:
- npm
- Yarn
npm install
yarn install
要检查是否成功更新,请运行:
- npm
- Yarn
npx docusaurus --version
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.