Docusaurus2 がやってくる

Facebook 製のドキュメントサイト ジェネレータである Docusaurus のバージョン2 (以下、Docusaurus2) が現在開発中のようです。（ GitHubのissue ）

公式ドキュメント: https://v2.docusaurus.io/

詳細な内容は上記ドキュメントを見ていただくとして、個人的に嬉しい点は次の3点です。

1. MDX がかけるようになる
2. 必要なディレクトリが1つになる
3. docs 内にサブディレクトリを作成可能になる

以下で詳細に述べます

1. MDX がかけるようになる

Markdown ファイルにJSX(React)が書けるようになります。これにより Markdown の書きやすさを保ちつつ、こだわって装飾したい箇所については柔軟に書きやすくなると思います。
ちなみに、Docusaurus2 ではプラグインシステムが導入されますが、MDXは追加プラグインは不要で、標準機能として使えます。

2. 必要なディレクトリが1つになる

Docusaurus1 ではプロジェクトディレクトリ内に docs と website の2ディレクトリがあって、好きではなかったのですが、 Docusaurus2 では website (名称は任意)の1ディレクトリだけとなり、スッキリしました。

Docusaurus1の構成

project
  ├── docs
  └── website
      ├── blog

↓

Docusaurus2の構成

project
  └── website
      ├── blog
      ├── docs

3. docs 内にサブディレクトリを作成可能になる

これが1番嬉しいポイントです。Docusaurus1 では docs 内にサブディレクトリを作ることができず、ファイルがフラットに羅列されていましたが Docusaurus2 ではサブディレクトリを作ることができ、ファイルのグループ化・階層化が行えます。
ただし、記事作成時点では公式ドキュメントにはそのような記述を見つけられず、正式にサポートされるのか、現在たまたまそのような挙動をしている（将来的に保証されない）のかは分かりません。
私も色々試していて偶然見つけただけです。

以下のような感じになります。

website/docs/foo/hoge.md

---
id: hoge
title: ほげ
---

text

website/docs/foo/fuga.md

---
id: fuga
title: ふが
---

text

website/docusaurus.config.js

module.exports = {
  ...,
  themeConfig: {
    navbar: {
      links: [
        { label: "ほげ", to: "docs/foo/hoge", position: 'left'},
      ],
    },
    ...,
  },
  ...,
}

website/sidebars.js

module.exports = {
  "docs": {
    "foo": ["foo/hoge", "foo/fuga"],
  },
};

docs/ が必要だったり、不要だったりで気付くのに苦労しました。

おまけ

scaffolded ツールは Docusaurus2 から scope 付き (@docusaurus/init) になっており、Docusaurus1 (docusaurus-init) とは棲み分けているようです。
これにより、Docusaurus2は記事作成時点ではまだアルファバージョンですが、あまり意識せずとも使用できます。（よくあるような バージョンタグを指定したり @next のようなエイリアスを指定する必要がない ）