FastAPI로 Docusaurus와 유사한 사이트 구축하기: 4단계 - Frontmatter 파싱

이전 글에서 Markdown 코드 블록에 대한 구문 강조 기능을 추가했습니다.

하지만 문서 페이지 제목({{ page_title }})이 main.py 라우트 함수 ("page_title": "Hello, Markdown!")에 여전히 하드코딩되어 있음을 발견했을 수 있습니다. 이는 매우 비유연적입니다. 이것은 새로운 문서를 추가할 때마다 코드를 수정해야 한다는 것을 의미할까요?

문서 사이트는 유연해야 하며, 언제든지 기사를 추가하거나 제거할 수 있어야 합니다. 기사의 제목, 작성자, 날짜와 같은 메타데이터는 콘텐츠와 마찬가지로 Markdown 파일 자체 내에 정의되어야 합니다.

이 글에서는 Frontmatter(Markdown 파일 상단에 메타데이터를 정의하는 일반적인 사양)를 소개하고 FastAPI가 이를 파싱하여 메타데이터를 동적으로 로드할 수 있도록 하겠습니다.

1단계: Frontmatter 파싱 라이브러리 설치

파일에서 Frontmatter와 Markdown 콘텐츠를 분리하고 파싱하기 위해 python-frontmatter를 사용할 것입니다.

다음 명령으로 설치하세요:

pip install python-frontmatter

2단계: Markdown 문서에 Frontmatter 추가

다음으로, docs/hello.md 파일을 수정하여 맨 위에 Frontmatter를 추가해 보겠습니다.

Frontmatter 블록은 삼중 하이픈(---)으로 둘러싸입니다.

docs/hello.md 업데이트:

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

... (나머지 Markdown 콘텐츠)

여기서 title, author, date 세 가지 메타데이터 필드를 정의했습니다. 필요에 따라 더 많은 필드를 추가할 수 있습니다. title 필드는 궁극적으로 기사의 page_title로 사용됩니다.

3단계: Frontmatter 파싱을 위해 `main.py` 수정

이제 get_hello_doc 라우트 함수를 수정하여 간단한 open().read() 대신 frontmatter 라이브러리를 사용하여 파일을 로드하도록 하겠습니다.

frontmatter.load() 함수는 파일을 두 부분으로 파싱합니다.

post.metadata: 모든 Frontmatter 데이터를 포함하는 사전 (예: {'title': 'Hello, Frontmatter!', ...}).
post.content: Markdown 콘텐츠의 본문만 포함하는 문자열입니다.

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  # 1. frontmatter 라이브러리 가져오기

app = FastAPI()

app.mount("/static", StaticFiles(directory="static"), name="static")

templates = Jinja2Templates(directory="templates")


# --- 홈 라우트 (변경 없음) ---
@app.get("/", response_class=HTMLResponse)
async def root(request: Request):
    context = {
        "request": request,
        "page_title": "Hello, Jinja2!" # (이미지와 일관성을 위해 원래 한국어로 유지되었지만, "Hello, Jinja2!"는 영어에 해당합니다.)
    }
    return templates.TemplateResponse("index.html", context)


# --- 2. 문서 라우트 수정 ---
@app.get("/docs/hello", response_class=HTMLResponse)
async def get_hello_doc(request: Request):
    """
    hello.md 문서를 읽고, 파싱하고 (Frontmatter 포함), 렌더링합니다.
    """
    md_file_path = "docs/hello.md"

    try:
        # 3. frontmatter.load를 사용하여 파일 읽기 및 파싱
        post = frontmatter.load(md_file_path)
    except FileNotFoundError:
        return HTMLResponse(content="<h1>404 - Document Not Found</h1>", status_code=404)
    except Exception as e:
        # 잘못된 형식의 YAML에 대한 일반적인 오류 처리 추가
        return HTMLResponse(content=f"<h1>500 - Parse Error: {e}</h1>", status_code=500)

    # 4. 메타데이터 및 콘텐츠 추출
    metadata = post.metadata
    md_content = post.content # 이것은 순수한 Markdown 콘텐츠입니다.

    # 5. Markdown 콘텐츠만 변환
    extensions = ['fenced_code', 'codehilite']
    html_content = markdown.markdown(md_content, extensions=extensions)

    # 6. 메타데이터에서 page_title 동적으로 가져오기
    #    'title' 키가 누락된 경우 충돌을 피하기 위해 .get() 사용
    page_title = metadata.get('title', 'Untitled Document')

    context = {
        "request": request,
        "page_title": page_title,    # 하드코딩된 값으로 대체
        "content": html_content
    }

    return templates.TemplateResponse("doc.html", context)