目次

• 背景
• Next.js と Chakra UI のテンプレートを導入
• Markdoc の導入
• 今回は普通のマークダウンで作成することにした
• まとめ

背景

Next.js で技術ブログを作成しています。
マークダウンで記事を作成して管理するつもりだったのですが、ちょうど作成し始めたときに Markdoc というサービスを知りました。
Markdoc | A powerful, flexible, Markdown-based authoring framework

Stripe が公開したサービスなんですね。
公式ドキュメントを見に行ったらリッチでいい感じだったので、導入してみようとした際のメモです。

Next.js と Chakra UI のテンプレートを導入

その前に、Next.js と Chakra UI で基本形を作りましょう。
公式に Next.js と Chakra UI のテンプレートがあるのでありがたく使わせていただきす。
next.js/examples/with-chakra-ui at canary · vercel/next.js · GitHub

yarn create next-app --example with-chakra-ui {アプリ名}

自動整形をしたいので、公式ページを見ながら環境を整えておきます。
Basic Features: ESLint | Next.js

まずはpackage.jsonに整形用のスクリプトを追加します。

"scripts": {
  "lint": "next lint"
}

早速コマンドを実行しましょう。

yarn lint

オプションはStrictにします。

Strict: Includes Next.js' base ESLint configuration along with a stricter Core Web Vitals rule-set. This is the recommended configuration for developers setting up ESLint for the first time.

prettier も入れましょうね。
Basic Features: ESLint | Next.js

yarn add --dev eslint-config-prettier

.eslintrc.jsonに設定を追加しましょう

{
  "extends": ["next/core-web-vitals", "prettier"]
}

それでは一旦起動してみましょう。

yarn dev

なんと既にダークモードに対応しています。
思わず何度も切り替えちゃいますね。

絶対パスを使いたいので、tsconfig.json に設定を追加しておきます。
Advanced Features: Absolute Imports and Module Path Aliases | Next.js

"compilerOptions": {
	"baseUrl": "src",
    "paths": {
      "@/components/*": ["components/*"]
    },
...

画像等を配置するため public ディレクトリも作成しておきましょう。

mkdir public

Markdoc の導入

記事の作成には Markdoc を使いたいです。
Markdoc | A powerful, flexible, Markdown-based authoring framework

普通のマークダウンで書けて、かつコールアウトとかのブロックも実装できるのが良さげです。
MDX とは違って、あくまで記事とコードは分離されるので、管理もわかりやすそうですね。
Next.js 向けのプラグインもあるみたいなので、早速導入してみましょう。
Markdoc | Using Markdoc with Next.js

ちなみに Markdoc×Next.js のテンプレートもあるので、人によってはこちらを使った方が早いかも？
GitHub - markdoc/markdoc-starter: Starter repo for quickly deploying a Markdoc app with Next.js

1. @markdoc/markdoc をインストールしましょう。

yarn add @markdoc/markdoc

2. Next.js 用に @markdoc/next.jsもインストールします。

yarn add @markdoc/next.js

3. next.config.jsに以下を追記します。

const withMarkdoc = require('@markdoc/next.js')

module.exports = withMarkdoc(/* options */)({
  pageExtensions: ['md', 'mdoc', 'js', 'jsx', 'ts', 'tsx'],
})

optionsではスキーマの場所やレンダリングのモードを設定することができます
next.config.js: Custom Page Extensions | Next.js

pageExtensionsについては以下を参照ください
next.config.js: Custom Page Extensions | Next.js

4. /pages/に.mdファイルを作成します

pages
├── _app.tsx
├── posts
│   └── hello-world.md
└── index.md

※ index.md の箇所ですが、おそらくこの手順の場合、この時点では index.tsx になっていると思いますのでmd ファイルに変更しておきましょう。
※ 中身は公式のサンプルをお借りしましょう。
markdoc-starter/index.md at main · markdoc/markdoc-starter · GitHub

5. 先ほどのマークダウンファイルに仮でテキストを入れておきましょう。

---
title: Hello Markdown
---

# {% $markdoc.frontmatter.title %}

Hello World Markdoc!!

6. markdoc の設定ファイルを配置するディレクトリを作ります。

mkdir markdoc

7. 公式を参考に各ファイルを用意していきましょう。
   markdoc-starter/markdoc at main · markdoc/markdoc-starter · GitHub

個人的に Markdoc 用のコンポーネントはまとまっていた方が見やすいので、components の下にディレクトリを追加します。

mkdir ./src/components/markdoc

以下を参考に、./src/components/markdoc に markdoc 用のコンポーネントも追加しておきましょう。
markdoc-starter/components at main · markdoc/markdoc-starter · GitHub

さて、アクセスして表示を確認してみましょう。

おおー。表示されました。
frontmatter に設定した内容も表示できていますね。
変数のように利用できるのは便利そうです。

今回は普通のマークダウンで作成することにした

Markdoc のドキュメントも Next.js ということで中身を見てみたけれど、慣れるまでちょっと癖がありそうに感じました。
（技術ブログとして色々やろうと思っている場合はちょっと慣れが必要かもしれない）
GitHub - markdoc/docs: Documentation site for Markdoc

逆に、ドキュメント管理に特化するのであればとても便利そうですね。
Docusaurusとかと競合になるのかしら？
Build optimized websites quickly, focus on your content | Docusaurus

よくよく考えると私がやりたかったのは情報発信であり、Markdoc で作ることではなかったです。
そもそも記事を発信するのが目的なので、今回はある程度慣れている技術でとりあえず作ってしまうことにします。

まとめ

Markdoc はリッチで便利そうなので、Docusaurus を使おうか悩んでいる場合は選択肢の一つにしても良いかもしれないなーと感じました。

※結局このブログは Next.js×Chakra UI×Markdown で作りました。