メインコンテンツへスキップ
バージョン: 3.5.2

バージョン管理されたサイト

まず、https://docusaurus.dokyumento.jp/blog/2018/09/11/Towards-Docusaurus-2#versioning を読んで、v1のアプローチの問題点を確認してください。

注意

バージョン管理されたドキュメントは通常、移行CLIによって正しく移行されるはずです。

versioned_docs のフロントマターを移行する​

v1とは異なり、各バージョン管理されたドキュメントのMarkdownヘッダーは、実際のIDフィールドの値としてversion-${version}-${original_id}を使用することで変更されなくなりました。より詳しい説明については、以下のシナリオをご覧ください。

たとえば、docs/hello.mdがあるとします。

---
id: hello
title: Hello, World !
---

Hi, Endilie here :)

新しいバージョン1.0.0をカットすると、Docusaurus v1では、website/versioned_docs/version-1.0.0/hello.mdはこのようになります。

---
id: version-1.0.0-hello
title: Hello, World !
original_id: hello
---

Hi, Endilie here :)

比較して、Docusaurus 2のwebsite/versioned_docs/version-1.0.0/hello.mdはこのようになります（元のものとまったく同じ）。

---
id: hello
title: Hello, World !
---

Hi, Endilie here :)

スナップショットを作成し、バージョン内でドキュメントを簡単に移動（および編集）できるようにするため、idフロントマターは変更されなくなり、同じままになります。内部的には、version-${version}/${id}として設定されます。

基本的に、各versioned_docsファイルに必要な変更点は次のとおりです。

---
- id: version-1.0.0-hello
+ id: hello
title: Hello, World !
- original_id: hello
---
Hi, Endilie here :)

versioned_sidebarsを移行する​

  • versioned_docsのIDを、version-${version}-${original_id}（v1）ではなく、version-${version}/${id}（v2）として参照します。

v1では、フロントマターID "version-${version}-${id}" を持つ新しいファイルが作成され、versioned_docs IDと競合する可能性が高いためです。

たとえば、Docusaurus 1はdocs/xxx.mdを区別できません。

---
id: version-1.0.0-hello
---

Another content

対 website/versioned_docs/version-1.0.0/hello.md

---
id: version-1.0.0-hello
title: Hello, World !
original_id: hello
---

Hi, Endilie here :)

v1およびv2ではフロントマターに/を使用できないため、競合が発生する可能性は低くなります。

そのため、v1ユーザーは、versioned_sidebarsファイルを移行する必要があります。

例 versioned_sidebars/version-1.0.0-sidebars.json

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"
    ]
  }
}

versioned_sidebarsおよびversioned_docsに入力する​

v2では、ドキュメントのバージョン管理にスナップショットアプローチを使用します。 すべてのバージョン管理されたドキュメントは、他のバージョンに依存しません。 version-1.0.0にfoo.mdがあるが、version-1.2.0には存在しないということが可能です。これは、Docusaurus v1のフォールバック機能（https://v1.docusaurus.io/docs/en/versioning#fallback-functionality）のため、以前のバージョンでは不可能でした。

たとえば、v1でversions.jsonがこのようになっている場合

versions.json
["1.1.0", "1.0.0"]

Docusaurus v1は、ドキュメントの内容が異なる場合のみ、バージョン管理されたドキュメントを作成します。v1.0.0からv1.1.0に変更されたドキュメントがhello.mdのみの場合、ドキュメント構造はこのようになる可能性があります。

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

v2では、不足しているversioned_docsとversioned_sidebarsを入力する必要があります（正しいフロントマターとID参照も含む）。

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

MDXでstyle属性をstyleオブジェクトに変換する​

Docusaurus 2では、ドキュメントファイルにJSXを使用します。Docusaurus 1のドキュメントにstyle属性がある場合は、次のようにstyleオブジェクトに変換してください。

---
id: demo
title: Demo
---

## Section

hello world

- pre style="background: black">zzz</pre>
+ pre style={{background: 'black'}}>zzz</pre>