Tailwind UIがリリースしたNext.js + Markdoc製ドキュメントテンプレート"Syntax"のコードを少し読んでみる

Syntaxは、Tailwind UIチームがリリースした、ドキュメントサイト向けテンプレートです。

![スクリーンショット 2022-07-12 14.55.22.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/a2cf0acb-278c-b21c-aa73-173de36c1aa2.png)
https://tailwindui.com/templates/syntax

Demo: https://syntax.tailwindui.com/


Next.jsを利用しており、マークダウンで記述されたドキュメントをMarkdocでページ化しています。

https://twitter.com/adamwathan/status/1526925883625328641

個人的にTailwind UIのライセンスを購入しており、テンプレートをDLできましたので、表示やコードを少しだけ紹介したいと思います。

## サイトコンテンツは、`src/pages/docs`にマークダウンで配置

サイトコンテンツはほぼ全てマークダウンファイルで管理されています。

MarkdocのNext.jsライブラリを利用しているため、`pages`ディレクトリ直下の`docs`配下に配置したマークダウンファイルが全てページになります。

```bash
$ tree src/pages/
src/pages/
├── _app.jsx
├── _document.jsx
├── docs
│   ├── architecture-guide.md
│   ├── basics-of-time-travel.md
...
│   └── writing-plugins.md
└── index.md

1 directory, 22 files
```

各ページのマークダウンファイルも、普段の書き方とほぼ同じです。

```markdown
---
title: Architecture guide
description: Quidem magni aut exercitationem maxime rerum eos.
---

Quasi sapiente voluptates aut minima non doloribus similique quisquam. In quo expedita ipsum nostrum corrupti incidunt. Et aut eligendi ea perferendis.

---

### Et pariatur ab quas

Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus.

```js
/** @type {import('@tailwindlabs/lorem').ipsum} */
export default {
  lorem: 'ipsum',
  dolor: ['sit', 'amet', 'consectetur'],
  adipiscing: {
    elit: true,
  },
}
```


### Markdocでの独自定義タグを利用する

Markdocでは、独自のタグを定義・利用できます。

Syntaxでも、`callout`タグなどの独自タグが実装されています。

```markdown

{% callout title="You should know!" %}
This is what a disclaimer message looks like.
{% /callout %}
```

独自定義タグは、React JSXライクに書くこともできます。
そのため、Reactユーザーであれば、カスタマイズに馴染みやすいかもしれません。

https://markdoc.io/docs/tags

`if`や`partial`など、[Markdocのビルトインタグ](https://markdoc.io/docs/tags#built-in-tags)も利用すると、より柔軟な運用が可能です。

### マークダウンファイルをSSRでページ化するか、SSGにするか

Next.jsを利用しているため、ページの生成をSSRかSSGから選ぶことができます。

MarkdocのNext.jsモジュールを使っている場合、`next.config.js`で`mode`の設定を行うと、生成方法を指定できます。

```diff_javascript
module.exports = withMarkdoc({
+  mode: 'server', // defaultは'static'
})(nextConfig)
```
Docs: https://markdoc.io/docs/nextjs#options

`mode: 'server'`に変更してビルドすると、SSRでページ生成を行うようになります。

```bash
Page                                       Size     First Load JS
┌ λ /                                      402 B           207 kB
├   /_app                                  0 B             161 kB
├ ○ /404                                   194 B           162 kB
├ λ /docs/architecture-guide               419 B           207 kB
├ λ /docs/basics-of-time-travel            423 B           207 kB
├ λ /docs/cacheadvance-flush               419 B           207 kB
├ λ /docs/cacheadvance-predict             419 B           207 kB
├ λ /docs/cacheadvance-regret              421 B           207 kB
├ λ /docs/cacheadvance-revert              421 B           207 kB
```

### `docs/`ディレクトリはネスト可能

複数のライブラリを紹介するなどで、マークダウンファイルをサブディレクトリに配置することもできます。

```bash
src/pages/docs/
├── architecture-guide.md
...
├── child
│   └── grand-child
│       ├── demo.md
│       └── index.md
└── writing-plugins.md
```

この場合、`https://example.com/docs/child/grand-child/demo`が`demo.md`のURLです。

`index.md`を配置した場合、`https://example.com/docs/child/grand-child/`がURLとなります。

なお、ナビゲーションメニューは自動生成ではありません。

`src/components/Layout.jsx`ファイルの`navigation`変数を更新しましょう。

```js
const navigation = [
  {
    title: 'Introduction',
    links: [
      { title: 'Getting started', href: '/' },
      { title: 'Installation', href: '/docs/installation' },
    ],
  },
  {
    title: 'Core concepts',
    links: [
      { title: 'Understanding caching', href: '/docs/understanding-caching' },
...
```

## 配色は一括置換が手軽そう

アクセントカラーなどの配色は、Tailwind CSSで要素ごとに指定されています。

そのため、配色を変更したい場合にはIDEの検索・置換を利用することになるかもしれません。

![スクリーンショット 2022-07-12 15.42.22.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/3adab0a2-2dce-e478-2c57-888183587401.png)

アクセントカラーを青からピンクに変更し、ダークモード固定にしたサンプルを用意してみました。

![スクリーンショット 2022-07-12 15.51.20.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2366300/e6253778-6c3c-c6cf-1091-0d307f1b2250.png)

## Markdoc + Next.jsでドキュメントサイトを作ろう

MarkdocはNext.js / HTML / React SPAそれぞれで利用できるnpmモジュールを公開しています。

https://www.npmjs.com/package/@markdoc/markdoc

https://www.npmjs.com/package/@markdoc/next.js

チュートリアルも用意されていますので、カスタマイズ性の高いドキュメントサイトやフレームワークを作りたい場合には、ぜひお試しください。

https://markdoc.io/docs/examples


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

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

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

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