mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-02 00:09:48 +02:00
misc: add command to run prettier on docs (#2102)
* misc: add command to run prettier on docs * Fix GH issue template * Fix tests * Add prettier-docs command to precommit
This commit is contained in:
parent
cfc313d7c7
commit
55e676cb25
141 changed files with 1181 additions and 968 deletions
|
@ -514,17 +514,21 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch
|
|||
> ⚠️ Although we've implemented docs versioning since 2.0.0-alpha.37, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work.
|
||||
|
||||
## Changes from v1
|
||||
|
||||
- Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem
|
||||
|
||||
### Migrate your versioned_docs frontmatter
|
||||
|
||||
- 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.
|
||||
|
||||
Example, you have a `docs/hello.md`.
|
||||
Example, you have a `docs/hello.md`.
|
||||
|
||||
```md
|
||||
---
|
||||
id: hello
|
||||
title: Hello, World !
|
||||
---
|
||||
|
||||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
|
@ -538,6 +542,7 @@ id: version-1.0.0-hello
|
|||
title: Hello, World !
|
||||
original_id: hello
|
||||
---
|
||||
|
||||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
|
@ -548,6 +553,7 @@ In comparison, Docusaurus 2 `website/versioned_docs/version-1.0.0/hello.md` look
|
|||
id: hello
|
||||
title: Hello, World !
|
||||
---
|
||||
|
||||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
|
@ -565,22 +571,23 @@ title: Hello, World !
|
|||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
|
||||
### Migrate your versioned_sidebars
|
||||
|
||||
- Refer to versioned_docs id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1).
|
||||
- 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.
|
||||
|
||||
Example, Docusaurus 1 can't differentiate `docs/xxx.md`
|
||||
|
||||
```md
|
||||
---
|
||||
id: version-1.0.0-hello
|
||||
---
|
||||
|
||||
Another content
|
||||
```
|
||||
|
||||
and `website/versioned_docs/version-1.0.0/hello.md`
|
||||
and `website/versioned_docs/version-1.0.0/hello.md`
|
||||
|
||||
```md
|
||||
---
|
||||
|
@ -588,6 +595,7 @@ id: version-1.0.0-hello
|
|||
title: Hello, World !
|
||||
original_id: hello
|
||||
---
|
||||
|
||||
Hi, Endilie here :)
|
||||
```
|
||||
|
||||
|
@ -596,6 +604,7 @@ Since we don't allow `/` in v1 & v2 for frontmatter, conflicts are less likely t
|
|||
So v1 users need to migrate their versioned_sidebars file
|
||||
|
||||
Example `versioned_sidebars/version-1.0.0-sidebars.json`:
|
||||
|
||||
```json {2-3,5-6,9-10}
|
||||
{
|
||||
+ "version-1.0.0/docs": {
|
||||
|
@ -617,12 +626,10 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`:
|
|||
In v2, we use snapshot approach on 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://docusaurus.io/docs/en/versioning#fallback-functionality).
|
||||
|
||||
For example, if your `versions.json` looks like this in v1
|
||||
|
||||
```json
|
||||
// versions.json
|
||||
[
|
||||
"1.1.0",
|
||||
"1.0.0"
|
||||
]
|
||||
["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`.
|
||||
|
@ -656,4 +663,4 @@ website
|
|||
├── versioned_sidebars
|
||||
│ ├── version-1.1.0-sidebars.json
|
||||
│ └── version-1.0.0-sidebars.json
|
||||
```
|
||||
```
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue