FastAPI で Docusaurus 風サイトを構築する：ステップ 5 - 静的ファイルの処理

前の記事では、Markdown Frontmatter の解析サポートを追加しました。これにより、ドキュメントのメタデータ（タイトルなど）をコンテンツと一緒に Markdown ファイル内で定義できるようになり、ハードコーディングを回避できます。

テキストやコードだけでなく、ドキュメントには通常、画像のような静的リソースが含まれます。

現在、hello.md で画像を参照しても表示されません。この記事では、Markdown ファイルで参照されている画像などの静的リソースを正しく処理して配信するように FastAPI を有効にすることで、この問題を解決します。

画像が表示されないのはなぜですか？

以下は、画像 leapcell-logo.png を含む Markdown ドキュメントです。

# Hello, Markdown!

Here is a Logo:
![Leapcell Logo](./leapcell-logo.png)

サーバーを実行してこのドキュメントにアクセスしても、画像は読み込まれません。

これは、画像のパスが ./leapcell-logo.png であるためです。ブラウザが /docs/hello ページからこのパスを要求すると、実際に要求される URL は http://127.0.0.1:8000/docs/leapcell-logo.png になります。

しかし、FastAPI アプリケーションには、/docs/leapcell-logo.png リクエストを処理するように構成されたルートまたはマount されたディレクトリがないため、画像は読み込まれません。

ステップ 2: ドキュメントリソースの規約を作成する

これらの画像を配信する方法が必要です。安易なアプローチは、すべての画像を static フォルダに置くことですが、より良い実践は、leapcell-logo.png のようなコンテンツリソースをメインの static ディレクトリから分離し、専用のフォルダ（例：docs/assets）に配置することです。

ディレクトリ構造を以下のように更新します：

fastapi-docs-site/
├── docs/
│   ├── assets/ <-- New
│   │   └── leapcell-logo.png <-- Resource file
│   └── hello.md
├── main.py
├── static/
│   └── css/
│       └── highlight.css
└── templates/

ステップ 3: ドキュメントリソースディレクトリを FastAPI にマウントする

次に、FastAPI に「/docs/assets/ で始まるリクエストは docs/assets/ フォルダ内のファイルを検索すべき」と指示する必要があります。

main.py を開き、次のように変更します。

# main.py
from fastapi import FastAPI, Request
from fastapi.templating import Jinja2Templates
from fastapi.responses import HTMLResponse
import markdown
from fastapi.staticfiles import StaticFiles
import frontmatter

app = FastAPI()

# これは新しく追加されたドキュメントコンテンツ用の「assets」ディレクトリです
# 注：マウントパスは「/docs/assets」、物理ディレクトリは「docs/assets」です
app.mount("/docs/assets", StaticFiles(directory="docs/assets"), name="doc_assets")

# その他のコードは変更されません

/docs ではなく /docs/assets をマウントしていることに注意してください。これはセキュリティのためです。assets フォルダ内の画像などのリソースのみを公開し、docs/ ディレクトリから .md ソースファイルを公開することは避けるようにします。

ステップ 4: Markdown の画像リンクを更新する

これで、設定された静的パスに従って Markdown で画像を（参照）できるようになります。

docs/hello.md を編集します：

---
title: Hello, Frontmatter!
author: FastAPI Developer
date: 2025-11-09
---

# Hello, Markdown!

This is the first Markdown document we've rendered with FastAPI.

Here is a Logo:

![Leapcell Logo](./assets/leapcell-logo.png)