【Markdown】nextra を使って簡単にドキュメントを作成する方法

August 8, 2023

nextra とは

nextra は、Next.js ベースの静的なドキュメントサイトを作成できるフレームワークです。

同じ React ベースのドキュメントフレームワークとして、Meta が開発している docusaurus がありますが、個人的には nextra の方が好きです。
(nextra は検索機能が algoria など外部のエンジンに頼らなくても使えたり、ドキュメントのみのサイトが作りやすかったりします)

nextra では mdx という、Markdown 内で JSX が使える記法に対応しているため、React で書いたコンポーネントなどが簡単に使えます。

また、Markdown を書くだけで勝手にサイドナビや目次を生成してくれたり、テーマやプラグインもカスタマイズできます。
Next.js の特徴でもあるハイパフォーマンスやプリレンダリング、ルーティングなどの機能もそのまま利用できます。

公式サイト: https://nextra.site/
GitHub リポジトリ: https://github.com/shuding/nextra

使ってみる

※Node.js v16 以上が必要です。

セットアップ

nextra にはテンプレートが用意されています。イチから構築するより手っ取り早いので、これを使います。

まず、テンプレートのリポジトリ (https://github.com/shuding/nextra-docs-template) にアクセスします。

Use this template から Create a new repository を選択します。

Repository name を入力し (ここでは「nextra-docs-test」にしました)、Create repository を押下します。

リポジトリが生成されたので、ローカルに clone してきます。

$ git clone [email protected]:Khsmty/nextra-docs-test.git

これで nextra を使って開発する準備が整いました 🎉

開発サーバーの起動

まず、pnpm を使ってパッケージをインストールします (pnpm が未インストールの場合は $ npm i -g pnpmでインストールしてください)

$ pnpm install

次に、コマンドを使って開発サーバーを起動していきます。

$ pnpm dev

その後、http://localhost:3000へアクセスすると、以下のような nextra の初期画面が表示されます。

これで nextra をローカルで立ちあげることができました 🎉

使える記法

Callout

説明文を中に入れられる箱です。
どのコンポーネントも入れられるので、もちろん画像を添えることも可能。

import { Callout } from 'nextra/components';

<Callout>
  ここに中身
</Callout>
<Callout type="info">
  info タイプ
</Callout>
<Callout type="warning">
  warning タイプ
</Callout>
<Callout type="error">
  error タイプ
</Callout>
<Callout emoji="🤖">
  カスタム絵文字
</Callout>

Steps

方法などをステップ単位で表すことができます。

import { Steps } from 'nextra/components';

<Steps>
### 材料を準備する
卵を用意します。
### 卵を割る
卵の殻を割り、中身をボウルに入れます。
### 混ぜる
卵の中身を泡立て器でよく混ぜます。
### 焼く
フライパンに油をひき、卵を流し入れます。
</Steps>

Tabs

タブを作成できます。条件分岐などがある場合に便利かと思います。

import { Tabs, Tab } from 'nextra/components';

<Tabs items={['だし巻き卵', '目玉焼き', 'スクランブルエッグ']}>
  <Tab>だし巻き卵は、よく溶いたたまごに出汁を加えて焼いた卵料理です。</Tab>
  <Tab>目玉焼きは、卵を目玉のような形に焼いた卵料理です。</Tab>
  <Tab>スクランブルエッグは、よく溶いた卵に牛乳や塩コショウなどを入れ、炒めた卵料理です。</Tab>
</Tabs>

File Tree

ファイルツリーを表示できます。ライブラリ等のドキュメントサイトに使う際に便利かと思います。
フォルダは開閉も可能です。

import { FileTree } from 'nextra/components';

<FileTree>
  <FileTree.Folder name="pages" defaultOpen>
    <FileTree.File name="_meta.json" />
    <FileTree.File name="contact.md" />
    <FileTree.File name="index.mdx" />
    <FileTree.Folder name="about">
      <FileTree.File name="_meta.json" />
      <FileTree.File name="legal.md" />
      <FileTree.File name="index.mdx" />
    </FileTree.Folder>
  </FileTree.Folder>
</FileTree>