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)

ステップ 5: 実行してテストする

uvicorn main:app --reload を実行してサーバーを起動します。

ブラウザで http://127.0.0.1:8000/docs/hello にアクセスします。

追加した leapcell-logo.png 画像がページに正しくレンダリングされていることがわかります。

まとめ

簡単な設定と規約により、Markdown ドキュメントに画像を含め、正しくレンダリングできるようになりました。

ドキュメントが増えるにつれて、サイトには利用可能なすべてのドキュメントをリストするサイドナビゲーションバーが必要です。もちろん、これも自動生成されるべきです。

次の記事では、docs/ ディレクトリを自動的にスキャンしてこのサイドバーを動的に生成し、サイトを「左サイドバー、右コンテンツ」レイアウトに変更します。

その他

サイトを構築した後、オンラインで公開して他の人に見てもらいたい場合があります。しかし、ほとんどのクラウドプラットフォームは高価であり、このような練習プロジェクトにお金を払う価値はありません。

デプロイのためにもっと経済的な方法はありませんか？ Leapcell を試すことができます。Python、Node.js、Go、Rust などの複数の言語のデプロイをサポートしており、毎月十分な無料枠が提供されているため、費用をかけずに最大 20 件のプロジェクトをデプロイできます。