mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-28 17:57:48 +02:00
176 lines
4.6 KiB
Text
176 lines
4.6 KiB
Text
---
|
|
slug: /migration/v2/versioned-sites
|
|
---
|
|
|
|
# Versioned sites
|
|
|
|
Read up https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.
|
|
|
|
:::note
|
|
|
|
The versioned docs should normally be migrated correctly by the [migration CLI](./migration-automated.mdx)
|
|
|
|
:::
|
|
|
|
## Migrate your `versioned_docs` front matter {#migrate-your-versioned_docs-front-matter}
|
|
|
|
Unlike v1, The Markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual ID field. See scenario below for better explanation.
|
|
|
|
For example, if you have a `docs/hello.md`.
|
|
|
|
```md
|
|
---
|
|
id: hello
|
|
title: Hello, World !
|
|
---
|
|
|
|
Hi, Endilie here :)
|
|
```
|
|
|
|
When you cut a new version 1.0.0, in Docusaurus v1, `website/versioned_docs/version-1.0.0/hello.md` looks like this:
|
|
|
|
```md
|
|
---
|
|
id: version-1.0.0-hello
|
|
title: Hello, World !
|
|
original_id: hello
|
|
---
|
|
|
|
Hi, Endilie here :)
|
|
```
|
|
|
|
In comparison, Docusaurus 2 `website/versioned_docs/version-1.0.0/hello.md` looks like this (exactly same as original)
|
|
|
|
```md
|
|
---
|
|
id: hello
|
|
title: Hello, World !
|
|
---
|
|
|
|
Hi, Endilie here :)
|
|
```
|
|
|
|
Since we're going for snapshot and allow people to move (and edit) docs easily inside version. The `id` front matter is no longer altered and will remain the same. Internally, it is set as `version-${version}/${id}`.
|
|
|
|
Essentially, here are the necessary changes in each versioned_docs file:
|
|
|
|
```diff {2-3,5}
|
|
---
|
|
- id: version-1.0.0-hello
|
|
+ id: hello
|
|
title: Hello, World !
|
|
- original_id: hello
|
|
---
|
|
Hi, Endilie here :)
|
|
```
|
|
|
|
## Migrate your `versioned_sidebars` {#migrate-your-versioned_sidebars}
|
|
|
|
- Refer to `versioned_docs` ID as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1).
|
|
|
|
Because in v1 there is a good chance someone created a new file with front matter ID `"version-${version}-${id}"` that can conflict with `versioned_docs` ID.
|
|
|
|
For example, Docusaurus 1 can't differentiate `docs/xxx.md`
|
|
|
|
```md
|
|
---
|
|
id: version-1.0.0-hello
|
|
---
|
|
|
|
Another content
|
|
```
|
|
|
|
vs `website/versioned_docs/version-1.0.0/hello.md`
|
|
|
|
```md
|
|
---
|
|
id: version-1.0.0-hello
|
|
title: Hello, World !
|
|
original_id: hello
|
|
---
|
|
|
|
Hi, Endilie here :)
|
|
```
|
|
|
|
Since we don't allow `/` in v1 & v2 for front matter, conflicts are less likely to occur.
|
|
|
|
So v1 users need to migrate their versioned_sidebars file
|
|
|
|
Example `versioned_sidebars/version-1.0.0-sidebars.json`:
|
|
|
|
```diff {2-3,5-6,9-10} title="versioned_sidebars/version-1.0.0-sidebars.json"
|
|
{
|
|
+ "version-1.0.0/docs": {
|
|
- "version-1.0.0-docs": {
|
|
"Test": [
|
|
+ "version-1.0.0/foo/bar",
|
|
- "version-1.0.0-foo/bar",
|
|
],
|
|
"Guides": [
|
|
+ "version-1.0.0/hello",
|
|
- "version-1.0.0-hello"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Populate your `versioned_sidebars` and `versioned_docs` {#populate-your-versioned_sidebars-and-versioned_docs}
|
|
|
|
In v2, we use snapshot approach for documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://v1.docusaurus.io/docs/en/versioning#fallback-functionality).
|
|
|
|
For example, if your `versions.json` looks like this in v1
|
|
|
|
```json title="versions.json"
|
|
["1.1.0", "1.0.0"]
|
|
```
|
|
|
|
Docusaurus v1 creates versioned docs **if and only if the doc content is different**. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is `hello.md`.
|
|
|
|
```bash
|
|
website
|
|
├── versioned_docs
|
|
│ ├── version-1.1.0
|
|
│ │ └── hello.md
|
|
│ └── version-1.0.0
|
|
│ ├── foo
|
|
│ │ └── bar.md
|
|
│ └── hello.md
|
|
├── versioned_sidebars
|
|
│ └── version-1.0.0-sidebars.json
|
|
```
|
|
|
|
In v2, you have to populate the missing `versioned_docs` and `versioned_sidebars` (with the right front matter and ID reference too).
|
|
|
|
```bash {3-5,12}
|
|
website
|
|
├── versioned_docs
|
|
│ ├── version-1.1.0
|
|
│ │ ├── foo
|
|
│ │ │ └── bar.md
|
|
│ │ └── hello.md
|
|
│ └── version-1.0.0
|
|
│ ├── foo
|
|
│ │ └── bar.md
|
|
│ └── hello.md
|
|
├── versioned_sidebars
|
|
│ ├── version-1.1.0-sidebars.json
|
|
│ └── version-1.0.0-sidebars.json
|
|
```
|
|
|
|
## Convert style attributes to style objects in MDX {#convert-style-attributes-to-style-objects-in-mdx}
|
|
|
|
Docusaurus 2 uses JSX for doc files. If you have any style attributes in your Docusaurus 1 docs, convert them to style objects, like this:
|
|
|
|
```diff
|
|
---
|
|
id: demo
|
|
title: Demo
|
|
---
|
|
|
|
## Section
|
|
|
|
hello world
|
|
|
|
- pre style="background: black">zzz</pre>
|
|
+ pre style={{background: 'black'}}>zzz</pre>
|
|
```
|