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 요청을 처리하도록 구성된 라우트나 마운트된 디렉토리가 없으므로 이미지가 로드되지 않습니다.

2단계: 문서 리소스에 대한 규칙 만들기

이러한 이미지를 제공할 방법이 필요합니다. 게으른 접근 방식은 모든 이미지를 static 폴더에 넣는 것이지만, 더 나은 방법은 leapcell-logo.png와 같은 콘텐츠 리소스를 기본 static 디렉토리에서 분리하여 예를 들어 docs/assets와 같은 전용 폴더에 배치하는 것입니다.

디렉토리 구조를 다음과 같이 업데이트하세요:

fastapi-docs-site/
├── docs/
│   ├── assets/           <-- 새로 추가
│   │   └── leapcell-logo.png   <-- 리소스 파일
│   └── 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개의 프로젝트를 배포할 수 있습니다.