みなさん、ドキュメント書くの好きですか？
ぼくは正直嫌いです。。。
「コーディングが終わった！」とおもったら、ドキュメント作業が残ってたときの絶望感や、「書かなきゃ」と思いつつもサボったりと、、、祭りのあとのお片付け感があり、どうしても好きになれない作業です。
そんなとき、たまたま見つけたのが Nextra です。
この Nextra を運用して半年ほど、コードとモノレポ構成にするだけで、嫌な作業から コーディングの一部 に変えられ、最高のドキュメント体験ができたので紹介します！
コードはすべて GitHub で公開していますので、よかったらぜひ
Nextra とは
Next.js と MDX で動く静的サイトジェネレーターで Markdown を書くだけで Web サイトが簡単につくれてしまいます！
その他には
- ダークモード
- フルテキストサーチ
- 多言語化
- Vercelへのデプロイ
と、機能も充実
開発者の Shu Ding 氏は、Next.js や SWR のコントリビュータとしても有名な方で、ここも抵抗感なく使いはじめられるポイントかもしれません！
当然 SWR のサイトページも Nextra で作られています。
モノレポ構成だと、なぜドキュメント管理しやすいか
そもそもは、書く行為そのものが面倒ですが...😅
それに輪をかけて作業タイミングに問題があります。
コードとドキュメントを別で管理している場合、コーディングしてPRが取り込まれて、その後まとまった単位でリリースされたら、ここでようやくドキュメント更新の必要性が訪れます。
ただ、残念ながらこの時点で、ほぼ多くの記憶が抜け落ちています。。。
逆にモノレポ構成にしておくと 同じPR上で作業 ができるので、記憶が鮮明なうちに修正でき、リリース後の作業からも開放されます。
ま、前置きはこの辺で、早速使い方を紹介しちゃいます！
セットアップ
インストール
ブログテンプレートを使う方は nextra-theme-docs → nextra-theme-blog に変えてください。
$ yarn add next react react-dom nextra nextra-theme-docs
設定
ここは、公式通りの設定です。これで Next.js 上で Nextra を動かす環境が整います。
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 を作成してメタ情報を記述しておきます。
export default {
logo: <span>My Nextra Documentation</span>,
project: {
link: 'https://github.com/shuding/nextra'
}
// ...
}
起動
お決まりの package.json の scripts に書いて yarn dev を実行すると、ローカル環境が立ち上がります！ プレビューを見ながら書きすすめてきましょうー
今回はモノレポ構成にしますので、本体コードとポートがかぶらないように -p 8000 とか指定しておくと良いでしょう。
"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 を配置してください。
ちなみに、こんな感じでルートディレクトリで docs を指定してスクリプトも実行できます（最近まで知らんかった）
yarn --cwd docs dev
Vercel へのデプロイ
最終関門であり、そして Nextra の最大の恩恵といえるのが Vercel へのデプロイです。
新しいプロジェクト作成から docs のディレクトリを指定すれば、main にマージされるたびにデプロイが走ってWebサイトも更新してくれます！！やったね 🙌
Gitlab-flow でブランチ管理されている場合は、Production branch を main から production に変えておくとよさそうです。
参考までに、個人開発で書いているドキュメントも貼っておきます。
まとめ
- Next.js と MDX で動く静的サイトジェネレーター
- コードとドキュメント修正を同じ PR で作業できる
- ブランチにマージしたら Vercel にデプロイされ公開作業も自動化！
- フリー
ということで、 Nextra とコードをモノレポ構成にするだけで、最高のドキュメント体験ができます！
それでは Happy Writing!!
Discussion