Next.jsとMarkdocで、マークダウンファイルからページを自動生成する

Markdocを利用すると、マークダウンで書いたコンテンツをHTMLへの変換が簡単にできます。

また、Next.js用モジュールも公開されているため、Next.jsで構築したサイトに組み込みやすいプロダクトです。

この記事では、MarkdocとNext.jsを利用し、作成したマークダウンファイルからページを自動生成する方法を紹介します。

## Step0: Next.jsのセットアップ

まずはNext.jsのアプリをセットアップしましょう。

```bash
$ npx create-next-app
✔ What is your project named? … markdoc-demo
Creating a new Next.js app in /Users/examples/next.js/markdoc-demo.

Using yarn.

Installing dependencies:
- react
- react-dom
- next

...
```

成功メッセージが表示されれば完了です。

```
Success! Created markdoc-demo at /Users/examples/next.js/markdoc-demo
Inside that directory, you can run several commands:

  yarn dev
    Starts the development server.

  yarn build
    Builds the app for production.

  yarn start
    Runs the built app in production mode.

We suggest that you begin by typing:

  cd markdoc-demo
  yarn dev
```

CLIを利用する場合、`cd markdoc-demo`でディレクトリを移動しましょう。

VS Codeであれば、`code markdoc-demo`でVS Codeを開くこともできます。

https://qiita.com/naru0504/items/c2ed8869ffbf7682cf5c

## Step1: Markdocライブラリを追加

ライブラリを追加しましょう。コアだけでなく、Next.js用ライブラリもインストールします。

```bash
$ npm install @markdoc/next.js @markdoc/markdoc
```

`package.json`の`dependencies`に`@markdoc/next.js`と`@markdoc/markdoc`が増えていれば成功です。

```diff_json

  "dependencies": {
+    "@markdoc/markdoc": "^0.1.3",
+    "@markdoc/next.js": "^0.1.6",
    "next": "12.2.2",
    "react": "18.2.0",
    "react-dom": "18.2.0"
  },
```

## Step2: `next.config.js`を更新する

`.md`ファイルからページを生成する必要があるため、必要なメソッドと設定の追加を行います。

```diff_javascript
/** @type {import('next').NextConfig} */
+const withMarkdoc = require('@markdoc/next.js');
const nextConfig = {
  reactStrictMode: true,
+  pageExtensions: ['jsx', 'tsx', 'md']
}

-module.exports = nextConfig
+module.exports = withMarkdoc()(nextConfig)
```

これで下準備ができました。

## Step3: マークダウンファイルを作成する

いよいよマークダウンファイルを作成しましょう。

今回の方法では、`pages/docs`以下に`.md`ファイルを配置する必要があります。

**`pages/docs/index.md`**
```
---
title: Hello Markdown
---

# {% $markdoc.frontmatter.title %}

Markdocを利用して、マークダウンファイルからWebページを生成します。
```

このファイルを保存した**後**、`npm run dev`でNext.jsアプリを起動しましょう。

```bash
$ npm run dev
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
```

http://localhost:3000/docs にアクセスすると、先ほど作成したマークダウンの内容が表示されます。

![スクリーンショット 2022-07-12 16.33.05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/020e850d-4ccf-304a-b24c-8ecc41983373.png)

## Step4: ページタイトルなど、Head要素を作成する

MarkdocのNext.js向けライブラリがページ生成を行いますが、ページタイトルなどのSEO・OGP系は現状未設定です。

カスタマイズする場合、`pages/_app.jsx`で`pageProps.markdoc`を利用しましょう。

```diff_jsx
import '../styles/globals.css'
import Head from 'next/head'

function MyApp({ Component, pageProps }) {
  return (
    <>
+    <Head>
+       {pageProps.markdoc ? <title>{pageProps.markdoc.frontmatter.title}</title> : null}
+    </Head>
    <Component {...pageProps} />
    </>
  )
}

export default MyApp
```

`pageProps.markdoc`は、MarkdocのNext.jsプラグインを通さずに生成されたページのみ取得できます。

そのため、`_app`で設定する場合は`null / undefined`のチェックを入れるようにしましょう。


## おわりに

Markdoc独自の機能を使う方法などは、以下の記事も参考になります。

https://qiita.com/kaonaga9/items/f0f0229c69b287f0d945

Markdocは独自タグやif文の実装など、カスタマイズ製の高いOSSですので、ぜひドキュメントサイトなどにお試しください。


## [PR] Stripe開発者向け情報をQiitaにて配信中！

- [Stripe Updates]：開発者向けStripeアップデート紹介・解説
- ユースケース別のStripe製品や実装サンプルの紹介
- Stripeと外部サービス・OSSとの連携方法やTipsの紹介
- 初心者向けのチュートリアル(予定)

など、Stripeを利用してオンラインビジネスを始める方法について週に２〜３本ペースで更新中です。

-> [Stripe Organizationsをフォローして最新情報をQiitaで受け取る](https://qiita.com/organizations/stripe)