前回の記事では、Markdown内での静的リソース（画像など）の読み込み問題を解決しました。
これまでのところ、ドキュメントページはコンテンツ、コードハイライト、画像をきれいに表示できます。しかし、読者はドキュメントのナビゲーションで依然として困難に直面しています。ページは孤立した島のようなものです：手動でURLを入力しない限り、ある記事から別の記事へジャンプすることはできません。
Docusaurusのようなドキュメントサイトは、通常、**「左サイドバー＋右コンテンツ」**レイアウトを使用します。
この記事では、この機能を実装します：docs/ ディレクトリ内のすべてのMarkdownファイルを自動的にスキャンし、そのタイトルを抽出し、サイドバーナビゲーションメニューを動的に生成する関数を作成します。
ステップ1：サイドバーレイアウトスタイルの作成
まず、ページレイアウトを元の「単一カラムの垂直構造」から「2カラムの水平構造」に変更する必要があります。
このレイアウトを定義するためには、新しいCSSファイルが必要です。static/css/ ディレクトリに layout.css ファイルを作成します。
更新されたファイル構造：
static/css/layout.css の編集：
ステップ2：HTMLテンプレートの変更
次に、templates/doc.html を変更して新しいCSSファイルを含め、サイドバーを収容するためにHTML構造を調整します。
テンプレートに新しい変数 sidebar_items を導入します。これはドキュメントのリストを含む配列であり、後でPythonコードから渡されます。
templates/doc.html の変更：
ステップ3：ディレクトリスキャンロジックの実装
ここで、docs/ フォルダをスキャンし、すべての .md ファイルを見つけて、それらのFrontmatterを解析してタイトルを取得するPythonコードを作成する必要があります。
main.py を開きます。pathlib ライブラリをインポート（os も使用できますが、pathlib の方がモダンです）し、ヘルパー関数を記述する必要があります。
main.py の変更：
ステップ4：テスト用の2番目のドキュメントを追加
サイドバーが実際に機能していることを確認するために、2番目のMarkdownファイルが必要です。
docs/ ディレクトリに setup.md を作成します。
ステップ5：実行とテスト
サーバーを起動するには uvicorn main:app --reload を実行します。
http://127.0.0.1:8000/docs/hello にアクセスします。
以下の変更に気づくでしょう：
- ページレイアウトが左サイドバーナビゲーションと右コンテンツエリアに変更されました。
- 左サイドバーには、「Hello, Frontmatter!
」と「Environment Setup Guide」の2つのリンクが自動的にリストされています。
しかし、小さな問題があります：
サイドバーの「Environment Setup Guide」をクリックすると、ブラウザは /docs/setup にジャンプします。この時点で、「コンテンツが見つかりません」というエラーが表示されるでしょう。
これは、現在の main.py には ハードコーディングされた /docs/hello ルートしかないため、/docs/setup を処理しないからです。
要約
ファイルシステムをスキャンすることで、ドキュメントサイトに目次を自動生成する機能を持たせました。docs/ フォルダに追加または削除した.mdファイルがいくつあっても、サイドバーは自動的に更新されます。
サイドバーはスマートですが、ルーティングは「ぎこちない」です。ルートアドレスはハードコーディングされているためです。もし100個のドキュメントがあったら、main.py に100個の @app.get("/docs/xxx") 関数を書くわけにはいかないでしょう？それは明らかに実行可能ではありません。
/docs/{any_filename} へのリクエストをキャプチャし、対応するMarkdownファイルを自動的に見つけるための汎用的な方法が必要です。
次の記事では、ファイルパスベースの動的ルーティングを実装し、404エラー問題を完全に解決し、サイドバーのすべてのリンクが実際に対応する記事にナビゲートすることを保証します。
その他
サイトを構築した後、オンラインで公開して他の人に見てもらいたいと思うかもしれません。しかし、ほとんどのクラウドプラットフォームは高価であり、このよう練習プロジェクトにお金を払うのは割に合いません。
デプロイにもっと経済的な方法はありませんか？Leapcellを試してみてください。Python、Node.js、Go、Rustのような複数の言語のデプロイをサポートしており、毎月十分な無料枠を提供しており、1円もかけずに最大20個のプロジェクトをデプロイできます。
Xでフォローする：@LeapcellJapan
関連記事：
