next

Translate

Installation

Docusaurus 的设计理念，最一开始就是要易于安装和使用，让你的网站可以快速架好并运行起来。

Important Note: we highly encourage you to use Docusaurus 2 instead.

安装 Docusaurus

我们为你归纳了一个实用的操作流程，它包括了建立 Docusaurus 站点基础架构需要执行的所有操作：

  1. 确保你已经安装了最新版的 Node。 此外我们建议你再装个 Yarn。

    Node 版本应不低于 10.9.0，Yarn 版本应不低于 1.5。

  2. 如果没有已经创建好的 Docusaurus 项目，则新建一个目录作为新项目的根目录，然后进入其中。

    你将在这个目录中创建文档。 根目录可能会包含其他文件。 Docusaurus 安装脚本会创建两个新的目录：docs 和 website。

    一般来说，把 Docusaurus 站点文件，存放在已有的或新建的 GitHub 项目目录下，是个不错的选择，不过 Docusaurus 并不强制要求你这样做。

  3. 运行 Docusaurus 安装脚本：npx docusaurus-init。

    如果你没有安装 Node 8.2 +，或是希望全局安装 Docusaurus，执行命令 yarn global add docusaurus-init 或 npm install --global docusaurus-init。 然后，执行命令 docusaurus-init。

验证安装

加上前面提到的几个文件和目录，现在你的 Docusaurus 项目的目录结构应该看起来像这个样子：

root-directory
├── Dockerfile
├── README.md
├── docker-compose.yml
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   ├── exampledoc4.md
│   └── exampledoc5.md
└── website
    ├── blog
    │   ├── 2016-03-11-blog-post.md
    │   ├── 2017-04-10-blog-post-two.md
    │   ├── 2017-09-25-testing-rss.md
    │   ├── 2017-09-26-adding-rss.md
    │   └── 2017-10-24-new-version-1.0.0.md
    ├── core
    │   └── Footer.js
    ├── package.json
    ├── pages
    ├── sidebars.json
    ├── siteConfig.js
    └── static

安装过程自动创建了一些 Docker 文件，这些文件并不是运行 Docusaurus 所必须的。 若要节省空间，可以把它们删掉，这并不会导致任何问题出现。 有关 Docker 的更多信息，请参阅 Docker 文档。

运行示例网站

在执行完安装 Docusaurus 一节中提到的 Docusaurus 初始化脚本docusaurus-init 之后，你会得到一个能够正常运行的示例网站，你可以基于它来建设自己的站点。 要运行这个示例：

  1. cd website

  2. 在 website 目录下，启动 Docusaurus 本地服务器，通过执行命令 yarn start 或 npm start。

  3. 如果示例站点没有自动打开，可以从 http://localhost:3000 访问它。 如果 3000 端口已被占用，将使用另一个端口。 查看控制台消息以确认使用了哪个端口。

    现在，你应该已经看到了浏览器中加载的示例站点。 与此同时，还有一个 LiveReload 服务也在运行，你对 website 目录中的文档和文件进行任何更改，都将实时刷新网页内容。 Docusaurus 会为你的网站随机生成一种主色和辅色。

使用代理软件后启动本地服务器

如果你使用了代理软件，那么你需要先禁用它，这样你对本地开发服务器的请求才能正常生效。 这可以通过使用 NO_PROXY 环境变量来完成。

SET NO_PROXY=localhost
yarn start （或 npm run start）

更新你的 Docusaurus 版本

安装好 Docusaurus 之后，你可以查看当前 Docusaurus 的版本号，通过在 website 目录下执行命令 yarn outdated docusaurus 或者 npm outdated docusaurus。

你会看到类似这样的输出结果：

$ yarn outdated
Using globally installed version of Yarn
yarn outdated v1.5.1
warning package.json: No license field
warning No license field
info Color legend :
 "<red>"    : Major Update backward-incompatible updates
 "<yellow>" : Minor Update backward-compatible features
 "<green>"  : Patch Update backward-compatible bug fixes
Package    Current Wanted Latest Package Type    URL
docusaurus 1.0.9   1.2.0  1.2.0  devDependencies https://github.com/facebook/docusaurus#readme
✨  Done in 0.41s.

如果执行 outdated 命令后，输出结果中没有重要版本更新提示，就意味着你正在使用的是最新版本。

你可以将 Docusaurus 更新到最新版本，通过执行命令：

yarn upgrade docusaurus --latest

或

npm update docusaurus

如果在升级之后你遇到了某些错误，可以试着清空你的 Babel 缓存（通常位于临时目录），或试着在设置了 BABEL_DISABLE_CACHE=1 的情况下启动 Docusaurus 服务器（例如，通过执行命令 yarn start）。

Site Preparation →