mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 16:59:06 +02:00
chore(v2): v2.0.0 alpha.44 (#2379)
* chore: v2.0.0-alpha.44 * chore: v2.0.0-alpha.44 * update CHANGELOG
This commit is contained in:
Yangshun Tay
GitHub
parent
c9ace3b7ed
commit
2b6e440970
32 changed files with 5138 additions and 35 deletions
|
|
@ -5,7 +5,7 @@ title: Design Principles
|
|||
|
||||
:::caution
|
||||
|
||||
_This section is a work in progress._
|
||||
This section is a work in progress.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ title: Lifecycle APIs
|
|||
|
||||
:::caution
|
||||
|
||||
_This section is a work in progress._
|
||||
This section is a work in progress.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -40,13 +40,19 @@ Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now
|
|||
// package.json
|
||||
{
|
||||
dependencies: {
|
||||
- "docusaurus": "^1.x.x",
|
||||
+ "@docusaurus/core": "^2.0.0-alpha.40",
|
||||
+ "@docusaurus/preset-classic": "^2.0.0-alpha.40",
|
||||
- "docusaurus": "^1.x.x",
|
||||
+ "@docusaurus/core": "^2.0.0-alpha.44",
|
||||
+ "@docusaurus/preset-classic": "^2.0.0-alpha.44",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Please use the most recent Docusaurus 2 alpha version, which you can check out [here](https://www.npmjs.com/package/@docusaurus/core) (it's tagged `next`).
|
||||
|
||||
:::
|
||||
|
||||
#### CLI commands
|
||||
|
||||
Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docusaurus-command`).
|
||||
|
|
@ -441,7 +447,7 @@ You'll have to migrate your sidebar if it contains category type. Rename `subcat
|
|||
|
||||
### Footer
|
||||
|
||||
`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
|
||||
`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run swizzle @docusaurus/theme-classic Footer
|
||||
|
|
@ -455,9 +461,10 @@ Please refer to [creating pages](creating-pages.md) to learn how Docusaurus 2 pa
|
|||
|
||||
`CompLibrary` is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://facebookincubator.github.io/infima/ to see what styles are available).
|
||||
|
||||
- The following code could be helpful for migration of various pages
|
||||
- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js),
|
||||
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js), [Flux](http://facebook.github.io/flux/support)
|
||||
The following code could be helpful for migration of various pages:
|
||||
|
||||
- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js)
|
||||
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js), [Flux](http://facebook.github.io/flux/support)
|
||||
|
||||
## Content
|
||||
|
||||
|
|
@ -521,25 +528,19 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch
|
|||
|
||||
:::caution
|
||||
|
||||
_This section is a work in progress._
|
||||
|
||||
:::
|
||||
|
||||
:::warning
|
||||
|
||||
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.
|
||||
The versioning feature is a work in progress! 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
|
||||
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
|
||||
### 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.
|
||||
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`.
|
||||
For example, if you have a `docs/hello.md`.
|
||||
|
||||
```md
|
||||
---
|
||||
|
|
@ -550,9 +551,7 @@ 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
|
||||
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
|
||||
---
|
||||
|
|
@ -589,13 +588,13 @@ title: Hello, World !
|
|||
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).
|
||||
- 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.
|
||||
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`
|
||||
For example, Docusaurus 1 can't differentiate `docs/xxx.md`
|
||||
|
||||
```md
|
||||
---
|
||||
|
|
@ -605,7 +604,7 @@ id: version-1.0.0-hello
|
|||
Another content
|
||||
```
|
||||
|
||||
and `website/versioned_docs/version-1.0.0/hello.md`
|
||||
vs `website/versioned_docs/version-1.0.0/hello.md`
|
||||
|
||||
```md
|
||||
---
|
||||
|
|
@ -639,7 +638,7 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`:
|
|||
}
|
||||
```
|
||||
|
||||
### Populate your versioned_sidebars & versioned_docs
|
||||
### Populate your `versioned_sidebars` and `versioned_docs`
|
||||
|
||||
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).
|
||||
|
||||
|
|
@ -665,7 +664,7 @@ website
|
|||
│ └── version-1.0.0-sidebars.json
|
||||
```
|
||||
|
||||
In v2, you have to populate the missing versioned_docs & versioned_sidebars (with the right frontmatter and id reference too).
|
||||
In v2, you have to populate the missing `versioned_docs` and `versioned_sidebars` (with the right frontmatter and id reference too).
|
||||
|
||||
```shell {3-5,12}
|
||||
website
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ keywords:
|
|||
- search
|
||||
---
|
||||
|
||||
Docusaurus's own `@docusaurus/preset-classic` supports a search integration.
|
||||
Docusaurus' own `@docusaurus/preset-classic` supports a search integration.
|
||||
|
||||
There are two main options, you can use [Algolia DocSearch](https://community.algolia.com/docsearch/) or bring in your own `SearchBar` component.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ title: '@docusaurus/theme-classic'
|
|||
|
||||
:::caution
|
||||
|
||||
_This section is a work in progress._
|
||||
This section is a work in progress.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
---
|
||||
id: versioning
|
||||
title: Versioning
|
||||
---
|
||||
|
||||
|
|
@ -12,9 +13,9 @@ Consider it really well before starting to version your documentation.
|
|||
|
||||
:::
|
||||
|
||||
Most of the times, you don't need versioning and it will just increase your build time and introduces complexity to your codebase. Versioning is **best suited for website with high-traffic and rapid changes in documentation between version**. If your documentation rarely changes, don't version.
|
||||
Most of the times, you don't need versioning and it will just increase your build time and introduces complexity to your codebase. Versioning is **best suited for website with high-traffic and rapid changes in documentation between version**. If your documentation rarely changes, don't add versions to the website.
|
||||
|
||||
To better understand how versioning works and see if it suits your needs, you can read up below.
|
||||
To better understand how versioning works and see if it suits your needs, you can read on below.
|
||||
|
||||
## Directory structure
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue