Nextra とコードのモノレポ構成が最高のドキュメント体験を与えてくれる

みなさん、ドキュメント書くの好きですか？

ぼくは正直嫌いです。。。

「コーディングが終わった！」とおもったら、ドキュメント作業が残ってたときの絶望感や、「書かなきゃ」と思いつつもサボったりと、、、祭りのあとのお片付け感があり、どうしても好きになれない作業です。

そんなとき、たまたま見つけたのが `Nextra` です。

https://nextra.site/

この Nextra を運用して半年ほど、コードとモノレポ構成にするだけで、嫌な作業から `コーディングの一部` に変えられ、最高のドキュメント体験ができたので紹介します！

コードはすべて GitHub で公開していますので、よかったらぜひ

https://github.com/superfastcms/superfast

# Nextra とは

Next.js と MDX で動く静的サイトジェネレーターで Markdown を書くだけで Web サイトが簡単につくれてしまいます！

その他には
- ダークモード
- フルテキストサーチ
- 多言語化
- Vercelへのデプロイ

と、機能も充実

開発者の Shu Ding 氏は、Next.js や SWR のコントリビュータとしても有名な方で、ここも抵抗感なく使いはじめられるポイントかもしれません！

当然 SWR のサイトページも Nextra で作られています。

https://swr.vercel.app/

# モノレポ構成だと、なぜドキュメント管理しやすいか

そもそもは、書く行為そのものが面倒ですが...😅

それに輪をかけて作業タイミングに問題があります。

コードとドキュメントを別で管理している場合、コーディングしてPRが取り込まれて、その後まとまった単位でリリースされたら、ここでようやくドキュメント更新の必要性が訪れます。

ただ、残念ながらこの時点で、ほぼ多くの記憶が抜け落ちています。。。

逆にモノレポ構成にしておくと **同じPR上で作業** ができるので、記憶が鮮明なうちに修正でき、リリース後の作業からも開放されます。

ま、前置きはこの辺で、早速使い方を紹介しちゃいます！

# セットアップ
## インストール

ブログテンプレートを使う方は `nextra-theme-docs` → `nextra-theme-blog` に変えてください。
~~~js
$ yarn add next react react-dom nextra nextra-theme-docs
~~~

## 設定

ここは、公式通りの設定です。これで Next.js 上で Nextra を動かす環境が整います。

~~~ts:next.config.js
const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx'
})
 
module.exports = withNextra()
 
// If you have other Next.js configurations, you can pass them as the parameter:
// module.exports = withNextra({ /* other next.js config */ })
~~~

最後に、プロジェクトのルートディレクトリに `theme.config.jsx` を作成してメタ情報を記述しておきます。

~~~ts:theme.config.jsx
export default {
  logo: <span>My Nextra Documentation</span>,
  project: {
    link: 'https://github.com/shuding/nextra'
  }
  // ...
}
~~~

## 起動

お決まりの package.json の scripts に書いて `yarn dev` を実行すると、ローカル環境が立ち上がります！ プレビューを見ながら書きすすめてきましょうー

今回はモノレポ構成にしますので、本体コードとポートがかぶらないように `-p 8000` とか指定しておくと良いでしょう。

~~~js:package.json
"scripts": {
  "dev": "next dev -p 8000",
  "build": "next build",
  "start": "next start -p 8000"
}
~~~

# Nextra の書き方

`pages/**/***.mdx` としてマークダウンファイルを設置します（拡張子が mdx なのは注意点です）。Next.jsでは、jsx や tsx などのファイルを pages 以下に配置しますが Nextra ではこの mdx がページに該当します。

たとえば、 `pages/about.mdx` という名前でファイルをつくると、 `https://example.com/about` というURLで記述したマークダウンの内容が確認できます。

# プロダクションコードとのモノレポ構成

と、ここまでで準備が整ったので、プロダクションコードに相乗りさせていきましょう。以下のようにルートディレクトリで、本体の `src` とドキュメントをまとめた `docs` を並べます。

`docs` ディレクトリには、さきほど作成した `next.config.js` や `theme.config.jsx` を配置してください。

![ディレクトリ構成](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/421112/3c1304dd-2006-3e1d-80ac-6b2a7a50481c.jpeg)

ちなみに、こんな感じでルートディレクトリで `docs` を指定してスクリプトも実行できます（最近まで知らんかった）

~~~js
yarn --cwd docs dev
~~~

# Vercel へのデプロイ

最終関門であり、そして Nextra の最大の恩恵といえるのが Vercel へのデプロイです。

![vercel](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/421112/bf51d842-1473-2853-db2c-70ab4325be33.png)

新しいプロジェクト作成から `docs` のディレクトリを指定すれば、main にマージされるたびにデプロイが走ってWebサイトも更新してくれます！！やったね 🙌

Gitlab-flow でブランチ管理されている場合は、Production branch を `main` から `production` に変えておくとよさそうです。

![vercel2](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/421112/8d1f0935-43a4-c8f3-57a6-13d9d2e06f11.png)

参考までに、個人開発で書いているドキュメントも貼っておきます。

https://superfastcms.vercel.app/

# まとめ
- Next.js と MDX で動く静的サイトジェネレーター
- コードとドキュメント修正を同じ PR で作業できる
- ブランチにマージしたら Vercel にデプロイされ公開作業も自動化！
- フリー

ということで、 Nextra とコードをモノレポ構成にするだけで、最高のドキュメント体験ができます！

それでは Happy Writing!!