Markdocを利用すると、マークダウンで書いたコンテンツをHTMLへの変換が簡単にできます。
また、Next.js用モジュールも公開されているため、Next.jsで構築したサイトに組み込みやすいプロダクトです。
この記事では、MarkdocとNext.jsを利用し、作成したマークダウンファイルからページを自動生成する方法を紹介します。
Step0: Next.jsのセットアップ
まずはNext.jsのアプリをセットアップしましょう。
$ 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を開くこともできます。
Step1: Markdocライブラリを追加
ライブラリを追加しましょう。コアだけでなく、Next.js用ライブラリもインストールします。
$ npm install @markdoc/next.js @markdoc/markdoc
package.jsonのdependenciesに@markdoc/next.jsと@markdoc/markdocが増えていれば成功です。
"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ファイルからページを生成する必要があるため、必要なメソッドと設定の追加を行います。
/** @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アプリを起動しましょう。
$ npm run dev
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
http://localhost:3000/docs にアクセスすると、先ほど作成したマークダウンの内容が表示されます。
Step4: ページタイトルなど、Head要素を作成する
MarkdocのNext.js向けライブラリがページ生成を行いますが、ページタイトルなどのSEO・OGP系は現状未設定です。
カスタマイズする場合、pages/_app.jsxでpageProps.markdocを利用しましょう。
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独自の機能を使う方法などは、以下の記事も参考になります。
Markdocは独自タグやif文の実装など、カスタマイズ製の高いOSSですので、ぜひドキュメントサイトなどにお試しください。
[PR] Stripe開発者向け情報をQiitaにて配信中！
- [Stripe Updates]：開発者向けStripeアップデート紹介・解説
- ユースケース別のStripe製品や実装サンプルの紹介
- Stripeと外部サービス・OSSとの連携方法やTipsの紹介
- 初心者向けのチュートリアル(予定)
など、Stripeを利用してオンラインビジネスを始める方法について週に２〜３本ペースで更新中です。