Syntaxは、Tailwind UIチームがリリースした、ドキュメントサイト向けテンプレートです。
https://tailwindui.com/templates/syntax
Demo: https://syntax.tailwindui.com/
Next.jsを利用しており、マークダウンで記述されたドキュメントをMarkdocでページ化しています。
個人的にTailwind UIのライセンスを購入しており、テンプレートをDLできましたので、表示やコードを少しだけ紹介したいと思います。
サイトコンテンツは、src/pages/docsにマークダウンで配置
サイトコンテンツはほぼ全てマークダウンファイルで管理されています。
MarkdocのNext.jsライブラリを利用しているため、pagesディレクトリ直下のdocs配下に配置したマークダウンファイルが全てページになります。
$ 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
各ページのマークダウンファイルも、普段の書き方とほぼ同じです。
---
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タグなどの独自タグが実装されています。
{% callout title="You should know!" %}
This is what a disclaimer message looks like.
{% /callout %}
独自定義タグは、React JSXライクに書くこともできます。
そのため、Reactユーザーであれば、カスタマイズに馴染みやすいかもしれません。
ifやpartialなど、Markdocのビルトインタグも利用すると、より柔軟な運用が可能です。
マークダウンファイルをSSRでページ化するか、SSGにするか
Next.jsを利用しているため、ページの生成をSSRかSSGから選ぶことができます。
MarkdocのNext.jsモジュールを使っている場合、next.config.jsでmodeの設定を行うと、生成方法を指定できます。
module.exports = withMarkdoc({
+ mode: 'server', // defaultは'static'
})(nextConfig)
Docs: https://markdoc.io/docs/nextjs#options
mode: 'server'に変更してビルドすると、SSRでページ生成を行うようになります。
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/ディレクトリはネスト可能
複数のライブラリを紹介するなどで、マークダウンファイルをサブディレクトリに配置することもできます。
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変数を更新しましょう。
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の検索・置換を利用することになるかもしれません。
アクセントカラーを青からピンクに変更し、ダークモード固定にしたサンプルを用意してみました。
Markdoc + Next.jsでドキュメントサイトを作ろう
MarkdocはNext.js / HTML / React SPAそれぞれで利用できるnpmモジュールを公開しています。
チュートリアルも用意されていますので、カスタマイズ性の高いドキュメントサイトやフレームワークを作りたい場合には、ぜひお試しください。
[PR] Stripe開発者向け情報をQiitaにて配信中！
- [Stripe Updates]：開発者向けStripeアップデート紹介・解説
- ユースケース別のStripe製品や実装サンプルの紹介
- Stripeと外部サービス・OSSとの連携方法やTipsの紹介
- 初心者向けのチュートリアル(予定)
など、Stripeを利用してオンラインビジネスを始める方法について週に２〜３本ペースで更新中です。