Nuxt3で始めるドキュメント管理のすすめ
Nuxt3で始めるドキュメント管理のすすめ
ドキュメントページを作る場合の選択肢はVuePress(VitePress)やgatsbyなどの静的サイトジェネレーターを使用する選択肢があります。
しかし、nuxt3 + nuxt contentという選択肢も非常に有用だと思ったため使い方の解説を記載します。
現在Nuxt3はSSG(nuxt generate)に対応していないためSSRとなりますが今後対応が進んでいくと思いますので今のうちに作成しておいて後々機能がリリースされたら改修を行っていく予定で使用しています。
なぜNuxtなのか
あくまでNuxtに常に優位があるわけではなく、既存のフレームワークとの別の需要を満たすものだと考えます。
この記事では主にVuePressとの比較を中心に記載していきます。
VuePressの場合インストールをして、簡単な設定だけでドキュメントを書きはじめることができます。
あくまでVuePressからの視点ですが、VuePressの公式ドキュメントにもNuxtとVuePress・VitePressの違いについて述べられています。
VuePressやVitePressは軽量でスピーディーなドキュメントページの作成が可能でNuxtはより高機能で拡張性のあるドキュメントページの作成を行うことが可能です。
簡単な図解ですが、Nuxtでドキュメントページを作成するメリットは
- 後からサーバー側のロジックも作成できる
- ログイン機能
- アクセス権限の管理など
- マークアップへの展開方法を柔軟に変更できる
というメリットが考えられます。
サクッとドキュメントページを作りたいというより、比較的大規模なドキュメントサイトの作成でメリットがあります。
Nuxt Contentを利用したMarkdown管理
Nuxt Contentを導入することでMarkdownのパース及び各種データの取得が可能になります。
通常であればMarkdownファイルをHTMLにパースして、ダイナミックルーティング機能などで表示内容を切り替えるという処理が必要かと思われますがNuxt Contentを使用するとその手間を大幅に減らすことができます。
例として自分のサイトでは、/post/をブログの一覧ページとして/post/<slug>という風にアクセスすることで記事を見れるようにしているのですがそのように設定する場合も可能です。
設定方法
設定方法としては、公式ドキュメントにもあるように
- パッケージのインストール
- 設定ファイルへの追加
- 記事ページが表示されるように設定
- 一覧ページの作成
という風に設定を行うだけで可能です。
インストール・設定
npm install --save-dev @nuxt/contentを実行して現在のプロジェクトにNuxt Contentをインストールします。
その後nuxt.config.tsのmodulesに'@nuxt/content'を追加することでパッケージを利用できるようになります。
また、設定の変更を行う場合はcontentという項目を作りその内部に設定を追加していくことが可能です。
// https://v3.nuxtjs.org/api/configuration/nuxt.config
export default defineNuxtConfig({
modules: [
'@nuxt/content',
],
content: {
// https://content.nuxtjs.org/api/configuration/
highlight: {
// コードハイライトを有効化する場合はテーマを設定
theme: 'github-dark-dimmed',
},
},
});
記事ページの表示
記事ページの表示を表示されるためには下記の作業が必要になります。
-
/pages/post/に[...slug].vueというファイルを作成 -
[...slug].vueファイルに<ContentDoc />コンポーネントを入れる -
/content/post/ディレクトリを作成 -
/content/post/にMarkdownファイルを作成
という手順を行い最終的に下記のようなディレクトリ構成を目指します。
root
┣ content
┃ ┗ post // pagesとパスを合わせておく
┃ ┗ // Markdownファイルを作成していく
┗ pages
┗ post // contentとパスを合わせる
┣ index.vue // 記事一覧ページ
┗ [...slug].vue // 記事ページ
ディレクトリを作成してファイルを作るだけなので解説が必要な箇所は少ないですが、contentディレクトリのMarkdownファイルを置く位置とpagesで表示のためのページのディレクトリは合わせておく必要があります。
ディレクトリを合わせることで、[...slug].vueの内部の記述は下記のようにシンプルな設定だけでページを表示できるようになります。
<template>
<div>
<ContentDoc />
</div>
</template>
<template>内部に記載した<ContentDoc />というコンポーネントが自動的にMarkdownファイルを展開して表示してくれます。
記事一覧の作成
記事の一覧ページとして/pages/post/index.vueを作成します。
こちらも一覧の表示には<ContentList></ContentList>というコンポーネントを使用することで表示することが可能です。
自分のサイトでは一度別のコンポーネントファイルとして定義して表示件数制限をpropsで渡せるようにしていますが基本的には変わりません。
<ContentList></ContentList>は子要素を受け取ることができるコンポーネントでpath=""でどのディレクトリにあるデータを取得するのか（content配下すべてであればpath=""）を指定可能です。
子要素に記事一覧データが配列として渡されるためv-forなどを使用して一覧を作成することができます。
具体的な記述方法は公式ドキュメントを参考にするとわかりやすいと思います。
| プロパティ | 説明 |
|---|---|
title |
記事のタイトル（front matterで設定されていない場合h1要素） |
description |
記事のディスクリプション（front matterで設定されていない場合最初のp要素） |
_path |
記事のパス |
また、記事データの配列は通常の配列と同様に操作が可能ですがArray.slice()などで複製後に操作を行わないと正しく表示されません。
記事の表示順を反転したい場合などはArray.slice().reverse()などで変更を行いましょう。
また、コンポーネントを使用せずにqueryContent()でsetup関数の内部で記事データを取得することも可能です。
このように<ContentList>もしくはqueryContent()を使用することでcontentのデータを取得することができます。
Proseコンポーネントによる柔軟なタグのパース
次に一番のオススメポイントでもあるProseコンポーネントの使い方を解説します。
Nuxt Contentには様々な機能がありますが、中でもProseコンポーネントを使用したタグの展開方法の変更が非常に優秀です。
Nuxtのcomponentsディレクトリにcontentというディレクトリを作成し、その中にProseコンポーネントを作成していくことでMarkdownから展開されるマークアップのスタイル定義やロジックの追加などが可能です。
下記のリンクにデフォルトのコンポーネントの定義があるため、この定義を上書きする形で同名のコンポーネントを作成することで定義を更新できます。
自分のプロジェクトにインストールされているものを確認したい場合は/node_modules/@nuxt/content/dist/runtime/components/Prose/内部に実際のコードが格納されています。
スタイルの定義などに使用することが多いですが、Vueのコンポーネントと同じように<script>内部にロジックを記載することが可能です。
自分のサイトではコードブロックに対してファイル名と言語を表示するようにスタイル・マークアップの変更を行っています。
Netlifyでの設定の容易さ
Netlifyでのデプロイはリポジトリを連携して、ビルドコマンドとパブリッシュディレクトリの指定を行うだけで可能です。
バックエンドの処理も自動的にNetlify functionを使用して実行してくれます。
また、NitroのドキュメントですがこちらにはZero Config Providerとして
が紹介されていますので、Netlify以外でも簡単にデプロイが可能なサービスも多そうです。
関連リンク
Discussion