分版
You can use the versioning CLI to create a new documentation version based on the latest content in the docs
directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs
directory continues to evolve.
在给你的文档划分版本之前,请三思——贡献者可能会更难帮助改进文档!
大多数情况下,你不需要划分文档版本,这样不仅会延长构建时间,还会把你的代码复杂化。 Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. 如果你的文档很少更改,请不要给你的文档划分版本。
为了深入了解版本化是怎么工作的,并查看它是否符合你的需要,你可以继续阅读下文。
Overview
典型的版本化文档网站如下所示:
website
├── sidebars.json # 当前文档版本的侧边栏
├── docs # 当前文档版本的文档目录
│ ├── foo
│ │ └── bar.md # https://mysite.com/docs/next/foo/bar
│ └── hello.md # https://mysite.com/docs/next/hello
├── versions.json # 表明哪些版本可用的文件
├── versioned_docs
│ ├── version-1.1.0
│ │ ├── foo
│ │ │ └── bar.md # https://mysite.com/docs/foo/bar
│ │ └── hello.md
│ └── version-1.0.0
│ ├── foo
│ │ └── bar.md # https://mysite.com/docs/1.0.0/foo/bar
│ └── hello.md
├── versioned_sidebars
│ ├── version-1.1.0-sidebars.json
│ └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json
The versions.json
file is a list of version names, ordered from newest to oldest.
下表解释了版本化的文件是如何从版本映射到生成的 URL 的。
路径 | 版本 | URL |
---|---|---|
versioned_docs/version-1.0.0/hello.md | 1.0.0 | /docs/1.0.0/hello |
versioned_docs/version-1.1.0/hello.md | 1.1.0(最新) | /docs/hello |
docs/hello.md | current | /docs/next/hello |
The files in the docs
directory belong to the current
docs version.
By default, the current
docs version is labeled as Next
and hosted under /docs/next/*
, but it is entirely configurable to fit your project's release lifecycle.
Terminology
请注意我们在这里使用的术语。
- Current version
- The version placed in the
./docs
folder. - Latest version / last version
- The version served by default for docs navbar items. Usually has path
/docs
.
Current version is defined by the file system location, while latest version is defined by the the navigation behavior. 它们可能是同一个版本,也可能不是同一个版本! (And the default configuration, as shown in the table above, would treat them as different: current version at /docs/next
and latest at /docs
.)
Tutorials
Tagging a new version
- First, make sure the current docs version (the
./docs
directory) is ready to be frozen. - 输入新的版本号。
- npm
- Yarn
- pnpm
npm run docusaurus docs:version 1.1.0
yarn docusaurus docs:version 1.1.0
pnpm run docusaurus docs:version 1.1.0
标记新版本时,文档分版机制会:
- Copy the full
docs/
folder contents into a newversioned_docs/version-[versionName]/
folder. - Create a versioned sidebars file based from your current sidebar configuration (if it exists) - saved as
versioned_sidebars/version-[versionName]-sidebars.json
. - Append the new version number to
versions.json
.
Creating new docs
- 把新文件放在相应版本的文件夹中。
- 根据版本号,在相应的侧边栏文件中添加新文件的引用。
- Current version structure
- Older version structure
# The new file.
docs/new.md
# Edit the corresponding sidebar file.
sidebars.js
# The new file.
versioned_docs/version-1.0.0/new.md
# Edit the corresponding sidebar file.
versioned_sidebars/version-1.0.0-sidebars.json