Build a Docusaurus-like Site with FastAPI: Step 4 - Parsing Frontmatter

#webdev #programming #backend #python

In the previous article, we added syntax highlighting for our Markdown code blocks.

But you might have noticed that the document page title ({{ page_title }}) is still hardcoded in the main.py route function ("page_title": "Hello, Markdown!"). This is very inflexible. Does this mean we have to modify the code every time we add a new document?

A documentation site needs to be flexible, allowing for articles to be added or removed at any time. The article's metadata—like its title, author, and date—should be defined within the Markdown file itself, just like the content.

In this article, we will introduce Frontmatter (a common specification for defining metadata at the top of a Markdown file) and enable FastAPI to parse it, allowing us to load metadata dynamically.

Step 1: Install the Frontmatter Parsing Library

We will use python-frontmatter to separate and parse the Frontmatter and the Markdown content from our files.

Install it with the following command:

pip install python-frontmatter

Step 2: Add Frontmatter to Our Markdown Document

Next, let's modify the docs/hello.md file to add Frontmatter at the very top.

A Frontmatter block is enclosed by triple dashes (---).

Update docs/hello.md:

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

... (Rest of the Markdown content)

We've defined three metadata fields here: title, author, and date. You can add more fields as needed. The title field will ultimately be used as the article's page_title.

Step 3: Modify `main.py` to Parse Frontmatter

Now, we'll modify the get_hello_doc route function to use the frontmatter library to load the file, instead of a simple open().read().

The frontmatter.load() function will parse the file into two parts:

post.metadata: A dictionary containing all the Frontmatter data (e.g., {'title': 'Hello, Frontmatter!', ...}).
post.content: A string containing only the main body of the Markdown content.

Open main.py and modify it as follows:

# 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. Import the frontmatter library

app = FastAPI()

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

templates = Jinja2Templates(directory="templates")


# --- Home route (unchanged) ---
@app.get("/", response_class=HTMLResponse)
async def root(request: Request):
    context = {
        "request": request,
        "page_title": "Hello, Jinja2!" # (Kept original Chinese for consistency with image, but "Hello, Jinja2!" is the English equivalent)
    }
    return templates.TemplateResponse("index.html", context)


# --- 2. Modify the document route ---
@app.get("/docs/hello", response_class=HTMLResponse)
async def get_hello_doc(request: Request):
    """
    Reads, parses (including Frontmatter), and renders the hello.md document
    """
    md_file_path = "docs/hello.md"

    try:
        # 3. Use frontmatter.load to read and parse the file
        post = frontmatter.load(md_file_path)
    except FileNotFoundError:
        return HTMLResponse(content="<h1>404 - Document Not Found</h1>", status_code=404)
    except Exception as e:
        # Add general error handling in case of malformed YAML
        return HTMLResponse(content=f"<h1>500 - Parse Error: {e}</h1>", status_code=500)

    # 4. Extract metadata and content
    metadata = post.metadata
    md_content = post.content # This is the pure Markdown content

    # 5. Convert only the Markdown content
    extensions = ['fenced_code', 'codehilite']
    html_content = markdown.markdown(md_content, extensions=extensions)

    # 6. Dynamically get the page_title from the metadata
    #    Use .get() to avoid crashing if the 'title' key is missing
    page_title = metadata.get('title', 'Untitled Document')

    context = {
        "request": request,
        "page_title": page_title,    # Replaced the hardcoded value
        "content": html_content
    }

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

Step 4: Run and Test

Run uvicorn main:app --reload to start the server.

Now, visit http://127.0.0.1:8000/docs/hello again.

You will see that the browser tab title and the <h1> tag on the page are no longer "Hello, Markdown!" but have been replaced with "Hello, Frontmatter!", which we just defined in the hello.md file's Frontmatter.

Conclusion and Next Steps

By introducing Frontmatter and the logic to parse it, our articles are now completely decoupled from the site itself.

Besides Markdown, a website also contains static files like images. How can we get FastAPI to deploy these static files correctly so they can be accessed online?

In the next article, we will solve this problem: handling static assets (like images) referenced in Markdown files, allowing them to be correctly deployed by FastAPI and displayed on the final webpage.

Other

After building your site, you might want to deploy it online for others to see. But most cloud platforms are expensive, and it's not worth paying a high price for a practice project like this.

Is there a more economical way to deploy? You can try Leapcell. It supports deploying multiple languages like Python, Node.js, Go, and Rust, and offers a generous free tier every month, allowing you to deploy up to 20 projects without spending a dime.