chore: rename 2.4.2 docs/changelog to 2.4.3 after bad publish (#9327)

website/versioned_docs/version-2.4.3/migration/migration-versioned-sites.mdx

@@ -0,0 +1,176 @@
+---
+slug: /migration/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>
+```