MENU
Khsmty
よわよわプログラマー
メイン言語は TypeScript。Rust を勉強中。
アーカイブ

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

  • URLをコピーしました!
目次

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>

まとめ

ドキュメントサイトを簡単に作成できる nextra を紹介してみました。

この記事がドキュメントサイトを構築する参考になれば幸いです。ここまでお読みいただきありがとうございました。

よかったらシェアしてね!
  • URLをコピーしました!

コメント

コメントする


目次