#MkDocs
7 件の記事
MkDocsでマニュアルを作る #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化
シリーズの最終回です。Materialの内蔵検索を整え、誰もが読めるようにするアクセシビリティ、そしてドキュメントを長く生かし続けるDocs as Code文化まで、運用の観点を整理してシリーズを締めくくります。
ドキュメントサイトジェネレーター比較 — Hugo・MkDocs・Docusaurus・Starlight、どれを選ぶか
チームのドキュメントを静的サイトで作ると決めたら、次の問いはどのツールで作るかです。Hugo・MkDocs・Docusaurus・Starlight の4つをランタイム・検索・バージョン管理・天井の観点で比較し、状況別に何を選べばよいかを整理します。
MkDocsでマニュアルを作る #5 多言語とバージョン管理
ひとつのドキュメントを複数の言語で提供し、製品バージョンが上がったときに古いドキュメントを一緒に維持する方法を扱います。mkdocs-static-i18nプラグインで多言語を、mikeでバージョンスナップショットとバージョンセレクターを付けるところまで整理します。
MkDocsでマニュアルを作る #4 Cloudflare Pagesでデプロイしてドメインをつなぐ
ローカルで作ったドキュメントを世に送り出します。requirements.txtで依存関係を固定し、GitHubに上げてCloudflare Pagesにつなぎ、カスタムドメインを付ける過程を整理します。MkDocs標準のデプロイであるgh-deployも併せて押さえます。
MkDocsでマニュアルを作る #3 コンテンツ作成 — コードブロック、Mermaid、admonition
ドキュメントを読みやすくする3つの要素を扱います。タイトルや行ハイライトが付くコードブロック、コードで描くMermaidの図、そして注意・警告を目立つように見せるadmonitionまで、MkDocs Materialでの使い方を整理します。
MkDocsでマニュアルを作る #2 navと検索 — ドキュメントの情報構造を整える
ドキュメントが数十編に増えても読者が迷わないためには、サイドバーと検索が要です。MkDocsでnavをmkdocs.ymlに直接設計し、Materialのナビゲーション機能と内蔵検索をオンにするところまで整理します。
MkDocsでマニュアルを作る #1 インストールから最初のドキュメントまで
MkDocsとMaterialテーマで、チームドキュメントや製品マニュアルのサイトの骨組みを立てます。Pythonの仮想環境へのインストールから、新しいサイトの作成、テーマの適用、ローカルサーバーで最初のドキュメントを表示するところまでを一気に進めます。