Forem: Leapcell

Build a Docusaurus-like Site with FastAPI: Step 6 - Sidebar Generation

Leapcell — Sat, 22 Nov 2025 18:53:53 +0000

In the previous article, we solved the issue of loading static resources (like images) within Markdown.

Up to this point, our documentation pages can display content, code highlighting, and images nicely. However, readers still face difficulties navigating the documentation. The pages are isolated islands: without manually typing the URL, you cannot jump from one article to another.

Documentation sites like Docusaurus typically use a "Left Sidebar + Right Content" layout.

In this article, we will implement this feature: we will write a function to automatically scan all Markdown files in the docs/ directory, extract their titles, and dynamically generate a sidebar navigation menu.

Step 1: Create Sidebar Layout Styles

First, we need to change the page layout from the original "single-column vertical structure" to a "two-column horizontal structure."

We need a new CSS file to define this layout. Create a layout.css file in the static/css/ directory.

Updated File Structure:

static/
└── css/
    ├── highlight.css
    └── layout.css    <-- New

Edit static/css/layout.css:

/* Global reset and basic styles */
body {
    margin: 0;
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
    color: #333;
}

/* Main container: Use Flexbox to implement side-by-side layout */
.main-container {
    display: flex;
    min-height: 100vh;
}

/* Left Sidebar Styles */
.sidebar {
    width: 250px;
    background-color: #f4f4f4;
    border-right: 1px solid #ddd;
    padding: 20px;
    flex-shrink: 0; /* Prevent sidebar from being compressed */
}

.sidebar h3 {
    margin-top: 0;
    font-size: 1.1rem;
    color: #555;
}

.sidebar ul {
    list-style: none;
    padding: 0;
}

.sidebar li {
    margin-bottom: 10px;
}

.sidebar a {
    text-decoration: none;
    color: #333;
    font-size: 0.95rem;
}

.sidebar a:hover {
    color: #007bff;
}

/* Right Content Area Styles */
.content {
    flex-grow: 1;
    padding: 20px 40px;
    max-width: 800px; /* Limit content max-width for better reading experience */
}

Step 2: Modify the HTML Template

Next, modify templates/doc.html to include the new CSS file and adjust the HTML structure to accommodate the sidebar.

We will introduce a new variable, sidebar_items, in the template. This will be an array containing the list of documents, which will be passed in from the Python code later.

Modify templates/doc.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{ page_title }} - My Docs Site</title>

    <link rel="stylesheet" href="{{ url_for('static', path='css/highlight.css') }}" />
    <link rel="stylesheet" href="{{ url_for('static', path='css/layout.css') }}" />
  </head>
  <body>

    <div class="main-container">
      <aside class="sidebar">
        <h3>Contents</h3>
        <ul>
          {% for item in sidebar_items %}
            <li>
              <a href="{{ item.url }}">{{ item.title }}</a>
            </li>
          {% endfor %}
        </ul>
      </aside>

      <main class="content">
        <h1>{{ page_title }}</h1>
        <hr />
        <div class="doc-content">{{ content | safe }}</div>
      </main>
    </div>

  </body>
</html>

Step 3: Implement Directory Scanning Logic

Now we need to write some Python code to scan the docs/ folder, find all .md files, and parse their Frontmatter to get the titles.

Open main.py. We need to import the pathlib library (you can also use os, but pathlib is more modern) and write a helper function.

Modify 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
from pathlib import Path # 1. Import Path

app = FastAPI()

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

templates = Jinja2Templates(directory="templates")

# --- Helper Function: Generate Sidebar Data ---
def get_sidebar_items():
    items = []
    docs_path = Path("docs")

    # Iterate over all .md files in the docs directory
    for file_path in docs_path.glob("*.md"):
        # Parse Frontmatter to get the title
        try:
            post = frontmatter.load(file_path)
            # If no title exists, use the filename
            title = post.metadata.get("title", file_path.stem) 
        except:
            title = file_path.stem

        # Generate URL, assuming the rule is /docs/{filename}
        # file_path.stem gets the filename without extension (e.g., "hello")
        url = f"/docs/{file_path.stem}"

        items.append({"title": title, "url": url})

    # Sort by title (or you can add an 'order' field to sort, here we simply sort by title)
    items.sort(key=lambda x: x["title"])
    return items

@app.get("/", response_class=HTMLResponse)
async def root(request: Request):
    # Homepage remains unchanged for now, we can add sidebar later
    context = {
        "request": request,
        "page_title": "Hello, Jinja2!"
    }
    return templates.TemplateResponse("index.html", context)

@app.get("/docs/hello", response_class=HTMLResponse)
async def get_hello_doc(request: Request):
    md_file_path = "docs/hello.md"

    try:
        post = frontmatter.load(md_file_path)
    except FileNotFoundError:
        return HTMLResponse(content="<h1>404 - Document Not Found</h1>", status_code=404)
    except Exception as e:
        return HTMLResponse(content=f"<h1>500 - Parse Error: {e}</h1>", status_code=500)

    metadata = post.metadata
    md_content = post.content

    extensions = ['fenced_code', 'codehilite']
    html_content = markdown.markdown(md_content, extensions=extensions)
    page_title = metadata.get('title', 'Untitled Document')

    # 2. Get sidebar data
    sidebar_items = get_sidebar_items()

    context = {
        "request": request,
        "page_title": page_title,
        "content": html_content,
        "sidebar_items": sidebar_items # 3. Pass to template
    }

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

Step 4: Add a Second Document for Testing

To verify that the sidebar is actually working, we need a second Markdown file.

Create setup.md in the docs/ directory:

---
title: Environment Setup Guide
author: Leapcell
date: 2025-11-10
---

# Project Environment Setup

This is our second document.

1. Install Python
2. Install FastAPI
3. Run Code

Step 5: Run and Test

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

Visit http://127.0.0.1:8000/docs/hello.

You will notice the following changes:

The page layout has changed to a left sidebar navigation and right content area.
The left sidebar automatically lists two links: "Hello, Frontmatter!" and "Environment Setup Guide".

However, there is a small problem:

If you click on "Environment Setup Guide" in the sidebar, the browser will jump to /docs/setup. At this point, you will see an error saying the content is not found.

This is because our main.py currently only has the hardcoded /docs/hello route and does not yet handle /docs/setup.

Summary

By scanning the file system, we have given our documentation site the ability to automatically generate a table of contents. No matter how many .md files you add to or remove from the docs/ folder, the sidebar will update automatically.

Although the sidebar is smart, the routing is "clumsy"—because the route addresses are hardcoded. If we have 100 documents, surely we can't write 100 @app.get("/docs/xxx") functions in main.py? That is obviously not viable.

We need a generic way to capture requests for /docs/{any_filename} and automatically find the corresponding Markdown file.

In the next article, we will implement File-path based Dynamic Routing, completely solving the 404 issue and ensuring that every link in the sidebar actually navigates to the corresponding article.

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.

Read other articles in this series

Related Posts:

Build a Docusaurus-like Site with FastAPI: Step 5 - Handling Static Files

Leapcell — Mon, 10 Nov 2025 21:34:47 +0000

In the previous article, we added support for parsing Markdown Frontmatter. This allows our document metadata (like the title) to be defined within the Markdown file along with the content, avoiding hard-coding.

Besides text and code, a document usually includes static resources like images.

Currently, if you reference an image in hello.md, it won't display. In this article, we will solve this problem by enabling FastAPI to correctly handle and serve static resources, like images, referenced in our Markdown files.

Why Won't the Image Display?

Here is a Markdown document that includes an image leapcell-logo.png:

# Hello, Markdown!

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

If you run the server and visit this document, the image will fail to load.

This is because the image path is ./leapcell-logo.png. When the browser requests this path from the /docs/hello page, the actual URL it requests is http://127.0.0.1:8000/docs/leapcell-logo.png.

However, in our FastAPI application, there are no routes or mounted directories configured to handle the /docs/leapcell-logo.png request, so the image fails to load.

Step 2: Create a Convention for Document Resources

We need a way to serve these images. The lazy approach would be to put all images in the static folder, but a better practice is to separate content resources (like leapcell-logo.png) from the main static directory and place them in a dedicated folder, for example, docs/assets.

Update the directory structure as follows:

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

Step 3: Mount the Document Resource Directory in FastAPI

Now, we need to tell FastAPI: "Any request beginning with /docs/assets/ should look for files in the docs/assets/ folder."

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

app = FastAPI()

# This is our newly added "assets" directory for document content
# Note: The mount path is "/docs/assets", the physical directory is "docs/assets"
app.mount("/docs/assets", StaticFiles(directory="docs/assets"), name="doc_assets")

# Other code remains unchanged

Note that we are mounting /docs/assets and not /docs. This is for security: we only want to expose resources like images in the assets folder, and avoid exposing the .md source files from the docs/ directory.

Step 4: Update the Image Link in Markdown

Now we can reference the image in Markdown according to our configured static path.

Edit 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)

Step 5: Run and Test

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

Visit http://127.0.0.1:8000/docs/hello in your browser.

You will see that the leapcell-logo.png image you added is now correctly rendered on the page.

Summary

With some simple configuration and conventions, we've enabled our Markdown documents to include images and render them correctly.

As we add more documents, our site should have a side navigation bar to list all available documents. Of course, this should also be generated automatically.

In the next article, we will dynamically generate this sidebar by automatically scanning the docs/ directory and change the site to a "left-sidebar, right-content" layout.

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.

Read other articles in this series

Related Posts:

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

Leapcell — Sun, 09 Nov 2025 23:02:22 +0000

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.

Read other articles in this series

Related Posts:

Build a Docusaurus-like Site with FastAPI: Step 3 - Code Highlighting

Leapcell — Fri, 07 Nov 2025 02:09:42 +0000

In the previous article, we added support for dynamically rendering HTML from .md files.

But as you saw, the Python code block in docs/hello.md was rendered, but it looked plain and had no color highlighting, making it difficult to read.

In this article, we'll solve this problem: using Pygments and python-markdown extensions to add syntax highlighting to our Markdown code blocks.

Step 1: Install Highlighting Dependencies

The python-markdown library supports extra features through "Extensions." To implement code highlighting, we need the codehilite extension, which in turn depends on another library: Pygments.

Execute the following command to install Pygments:

pip install Pygments

Step 2: Configure Static Files Directory and CSS

The way syntax highlighting works is a two-step process:

python-markdown's codehilite extension converts code blocks (e.g., python ...) into HTML tags with specific CSS classes (like .k for keyword, .s for string).
Use a CSS file to tell the browser what colors these CSS classes should display.

The Pygments library provides a convenient command-line tool to generate this CSS.

First, let's create a static/css folder in our project's root directory to store this CSS file.

fastapi-docs-site/
├── docs/
│   └── hello.md
├── main.py
├── static/
│   └── css/          <-- New
└── templates/

Step 3: Generate the Highlighting CSS File

Open your terminal and run the following command:

pygmentize -S monokai -f html -a .codehilite > static/css/highlight.css

Here's an explanation of the pygmentize parameters:

-S monokai: Specifies monokai as the highlighting theme (you can also try default, github-dark, solarized-light, etc.).
-f html: -f indicates that we want to generate CSS for HTML.
-a .codehilite: -a means all CSS rules should be nested under the .codehilite CSS class (this is the default class used by python-markdown).

After it finishes, open static/css/highlight.css, and you'll see the CSS rules for the monokai theme have been generated inside.

Step 4: Mount the Static Directory in FastAPI

Now we have the CSS file, but FastAPI doesn't know about it yet. To fix this, we need to "mount" the static directory in main.py.

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 # 1. Import StaticFiles

app = FastAPI()

# 2. Mount the static directory
# This tells FastAPI that any request starting with /static
# should look for files in the "static" folder
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!"
    }
    return templates.TemplateResponse("index.html", context)


# --- Doc route (to be modified next) ---
@app.get("/docs/hello", response_class=HTMLResponse)
async def get_hello_doc(request: Request):
    md_file_path = "docs/hello.md"
    try:
        with open(md_file_path, "r", encoding="utf-8") as f:
            md_content = f.read()
    except FileNotFoundError:
        return HTMLResponse(content="<h1>404 - Document Not Found</h1>", status_code=404)

    # Unchanged for now, we will modify it in the next step
    html_content = markdown.markdown(md_content)

    context = {
        "request": request,
        "page_title": "Hello, Markdown!",
        "content": html_content
    }
    return templates.TemplateResponse("doc.html", context)

Step 5: Include the CSS in the HTML Template

Modify templates/doc.html, adding a <link> tag in the <head> so the HTML page can load the code highlighting CSS:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{ page_title }} - My Docs Site</title>

    <link
      rel="stylesheet"
      href="{{ url_for('static', path='css/highlight.css') }}"
    />
  </head>
  <body>
    <h1>{{ page_title }}</h1>

    <hr />

    <div class="doc-content">{{ content | safe }}</div>
  </body>
</html>

Step 6: Enable Markdown Extensions

For the final step, let's return to main.py and tell the python-markdown library to use the codehilite extension during conversion.

We also need the fenced_code extension, which is used to render content within triple backticks as code blocks, a necessary condition for displaying syntax highlighting.

Modify the get_hello_doc route function in main.py:

# main.py

# ... (other imports and app instance remain unchanged) ...

# ... (app.mount and templates instance remain unchanged) ...

# ... (root home route remains unchanged) ...


@app.get("/docs/hello", response_class=HTMLResponse)
async def get_hello_doc(request: Request):
    """
    Read, parse, and render the hello.md document (with syntax highlighting)
    """
    md_file_path = "docs/hello.md"

    try:
        with open(md_file_path, "r", encoding="utf-8") as f:
            md_content = f.read()
    except FileNotFoundError:
        return HTMLResponse(content="<h1>404 - Document Not Found</h1>", status_code=404)

    # Key change: enable markdown extensions
    # 1. fenced_code: Supports `` ` syntax
    # 2. codehilite: Enables syntax highlighting (it will automatically use Pygments)
    extensions = ['fenced_code', 'codehilite']
    html_content = markdown.markdown(md_content, extensions=extensions)

    context = {
        "request": request,
        "page_title": "Hello, Markdown!",
        "content": html_content
    }

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

Step 7: 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 find that the Python code block in hello.md now has monokai theme syntax highlighting. You can also try changing the parameters when generating the CSS to see the effects of other highlighting themes.

Deploying the Project Online

A docs site is meant to be visited by everyone, so just running it locally isn't enough. Next, we can deploy it online.

A simple deployment option is to use Leapcell. It's a web app hosting platform that can host projects in various languages and frameworks, including FastAPI, of course.

Follow the steps below:

1.Register an account on the website.

2.Commit your project to GitHub. You can refer to GitHub's official documentation for the steps. Leapcell will pull the code from your GitHub repository later.

3.Click "Create Service" on the Leapcell page.

4.After choosing your FastAPI repo, you'll see Leapcell has auto-populated the necessary configurations.

5.Click "Submit" at the bottom to deploy. The deployment will complete quickly and return you to the deployment homepage. Here we can see that Leapcell has provided a domain. This is the online address of your blog.

Conclusion and Next Steps

With syntax highlighting, your documentation site looks much more professional.

But there's still one problem: the page title ({{ page_title }}) in the doc.html template is still hard-coded in the route function in main.py ("page_title": "Hello, Markdown!") instead of being retrieved from the Markdown file.

This is very inflexible. The correct approach is for this title to also be read from the hello.md file itself.

In the next article, we will introduce Frontmatter (used to define article metadata like title, date, etc.) in our Markdown files and implement Frontmatter parsing and reading in our project to avoid hard-coding in our code.

Read other articles in this series

Related Posts:

Build a Docusaurus-like Site with FastAPI: Step 2 - Render Markdown

Leapcell — Tue, 04 Nov 2025 21:59:06 +0000

In the previous article, we set up a FastAPI service and used Jinja2 to render a dynamic HTML template.

But if you've used other documentation site tools, you'll know they all work by writing Markdown, which they then use to generate HTML content, rather than writing HTML by hand.

In this article, we will implement this exact feature: reading a local .md file, parsing it into HTML, and injecting it into our web template.

Step 1: Install a Markdown Parsing Library

We need a tool to convert Markdown text into an HTML string. A popular library for this is python-markdown.

Install it by running the following command:

pip install markdown

Step 2: Create Our First Markdown Document

By convention, we will store all our source documents in a new docs/ folder.

First, create a docs folder in your project's root directory, and then create a hello.md file inside it.

Updated project structure:

fastapi-docs-site/
├── docs/               <-- New
│   └── hello.md        <-- New
├── main.py
├── static/
└── templates/

Edit docs/hello.md:
Open this new file and write some Markdown content so we can test it later.

# Hello, Markdown!

This is our first Markdown document rendered with FastAPI.

Here is a code block example (though it doesn't have syntax highlighting yet):

``python
def say_hello():
    print("Hello from FastAPI!")
``

  - This is a list item
  - This is another list item

Step 3: Create a Template for Rendering Documents

The templates/index.html we created in the last article is our homepage. Now, we need a dedicated template to display the content of this Markdown file.

Create a new file in the templates/ folder named doc.html.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{ page_title }} - My Docs Site</title>
  </head>
  <body>
    <h1>{{ page_title }}</h1>

    <hr />

    <div class="doc-content">{{ content | safe }}</div>
  </body>
</html>

{{ content | safe }} tells Jinja2: "The content in this content variable is safe HTML. Please render it directly and do not escape it."

Step 4: Create the Markdown Rendering Route

Next, let's modify main.py to add a new route for our Markdown file, for example, /docs/hello.

It will perform the following actions:

Read the contents of the docs/hello.md file.
Import the markdown library.
Use the markdown.markdown() function to convert the file content into an HTML string.
Pass this HTML string as the content variable to the doc.html template.

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

app = FastAPI()

templates = Jinja2Templates(directory="templates")


# --- This is the homepage route from the previous article ---
@app.get("/", response_class=HTMLResponse)
async def root(request: Request):
    """
    Root route, returns the rendered HTML template
    """
    context = {
        "request": request,
        "page_title": "Hello, Jinja2!"
    }
    return templates.TemplateResponse("index.html", context)


# --- 2. This is our new documentation route ---
@app.get("/docs/hello", response_class=HTMLResponse)
async def get_hello_doc(request: Request):
    """
    Read, parse, and render the hello.md document
    """

    # 3. Hard-code the path to the Markdown file
    # (We will make this dynamic in a future article)
    md_file_path = "docs/hello.md"

    try:
        with open(md_file_path, "r", encoding="utf-8") as f:
            md_content = f.read()
    except FileNotFoundError:
        # Simple error handling
        return HTMLResponse(content="<h1>404 - Document not found</h1>", status_code=404)

    # 4. Use the markdown library to convert it to HTML
    html_content = markdown.markdown(md_content)

    # 5. Prepare the template context
    #    Note that we are now rendering doc.html
    context = {
        "request": request,
        "page_title": "Hello, Markdown!", # Temporarily hard-coded title
        "content": html_content         # Pass in the converted HTML
    }

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

Step 5: Run and Test

Start your server by running uvicorn main:app --reload.

In your browser, visit this URL: http://127.0.0.1:8000/docs/hello

You should see the content of docs/hello.md successfully rendered as an HTML page!

Deploying the Project Online

A docs site is meant to be visited by everyone, so just running it locally isn't enough. Next, we can deploy it online.

A simple deployment option is to use Leapcell. It's a web app hosting platform that can host projects in various languages and frameworks, including FastAPI, of course.

Follow the steps below:

1.Register an account on the website.

2.Commit your project to GitHub. You can refer to GitHub's official documentation for the steps. Leapcell will pull the code from your GitHub repository later.

3.Click "Create Service" on the Leapcell page.

4.After choosing your FastAPI repo, you'll see Leapcell has auto-populated the necessary configurations.

Summary and Next Steps

With this article, we have implemented the most core feature of a documentation site: dynamic Markdown-to-HTML conversion.

You probably noticed the Python code block in hello.md. Although it was correctly rendered as code, it looks plain, has no color highlighting, and is hard to read.

This is clearly not the experience a documentation site should provide.

In the next article, we will solve this problem: adding syntax highlighting to our rendered Markdown code blocks.

Read other articles in this series

Related Posts:

Build a Docusaurus-like Site with FastAPI: Step 1 - HTML Template

Leapcell — Tue, 04 Nov 2025 16:49:17 +0000

There are many documentation site tools available, but as you try them, you've likely found it frustrating. It seems no single tool meets all your specific needs while remaining simple enough to use.

If that's the case, why not build your own?

In the following series of articles, we will gradually build a documentation site similar to Docusaurus.

This is the first article. We'll start by building a simple backend service that returns a dynamic HTML template page.

Step 1: Environment Setup and Dependency Installation

First, we need to create a project directory and install the necessary dependencies.

Create the project directory:

mkdir fastapi-docs-site
cd fastapi-docs-site

Install core dependencies:
We will install three key libraries:

fastapi: Our web framework.
uvicorn[standard]: The ASGI server to run FastAPI.
jinja2: The engine used for rendering HTML templates.

pip install fastapi "uvicorn[standard]" jinja2

Step 2: Set Up the Project Skeleton

Next, create the following files and folders in the fastapi-docs-site root directory:

fastapi-docs-site/
├── main.py           # Our main FastAPI application file
├── static/           # To store static files like CSS, JS, images
└── templates/        # To store Jinja2 HTML templates

main.py: This will hold all our FastAPI application logic and routes.
templates/: Jinja2 will look for HTML template files here by default.
static/: FastAPI will use this directory to serve static files (we'll use this in a future article).

Step 3: Write Your First FastAPI App (JSON Version)

Before we start with template rendering, let's first ensure that FastAPI itself is working correctly.

Open main.py and enter the following basic code:

# main.py
from fastapi import FastAPI

# Instantiate the FastAPI app
app = FastAPI()

@app.get("/")
async def root():
    """
    Root route, returns a simple JSON response
    """
    return {"message": "Hello FastAPI"}

Open your terminal, make sure you are in the fastapi-docs-site root directory, and run:

uvicorn main:app --reload

main:app refers to the app = FastAPI() instance created in main.py.
--reload: This parameter watches for your code changes and automatically restarts the server.

Now, open your browser and visit http://127.0.0.1:8000. You should see:

{ "message": "Hello FastAPI" }

Step 4: Configure the Jinja2 Template Engine

Great, the server is running. But we want HTML, not JSON.

We need to tell FastAPI how to find and use our templates directory.

Modify main.py:

# main.py
from fastapi import FastAPI
# Import Jinja2Templates
from fastapi.templating import Jinja2Templates

# Instantiate the FastAPI app
app = FastAPI()

# Key step: Configure the template directory
# The string "templates" must match the folder name you created
templates = Jinja2Templates(directory="templates")


@app.get("/")
async def root():
    # Keep this as is for now, we'll change it in the next step
    return {"message": "Hello FastAPI"}

Step 5: Create Our First HTML Template

In the templates/ folder, create a new file: index.html.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Docs Site</title>
  </head>
  <body>
    <h1>{{ page_title }}</h1>
    <p>Welcome to our first dynamic page!</p>
  </body>
</html>

Notice <h1>{{ page_title }}</h1>. This isn't pure HTML. {{ ... }} is Jinja2's variable syntax. We will soon pass a value (like "Homepage") dynamically from our FastAPI backend to this page_title variable.

Step 6: Render the Template with TemplateResponse

Final step, let's modify the root route / so it no longer returns JSON, but instead renders our index.html template.

To do this, we need to import the following tools:

Request: This is required for Jinja2 to be able to build correct URLs and context.
HTMLResponse: A response class provided by FastAPI specifically for returning HTML.

Modify main.py as follows:

# main.py
from fastapi import FastAPI, Request  # Import Request
from fastapi.templating import Jinja2Templates
from fastapi.responses import HTMLResponse # Import HTMLResponse

app = FastAPI()

templates = Jinja2Templates(directory="templates")


# Note: The route function signature now includes request: Request
@app.get("/", response_class=HTMLResponse)
async def root(request: Request):
    """
    Root route, returns the rendered HTML template
    """
    # 1. The template file name
    template_name = "index.html"

    # 2. The context to pass to the template
    #    "request" is required
    #    "page_title" is our custom variable, corresponding to {{ page_title }} in the HTML
    context = {
        "request": request,
        "page_title": "Hello, Jinja2!"
    }

    return templates.TemplateResponse(template_name, context)

If you had --reload enabled, your server should have restarted automatically.

Refresh the page http://127.0.0.1:8000.

You will find the JSON has disappeared, replaced by a rendered HTML page, and the content of the <h1> tag has been dynamically replaced.

Deploying the Project Online

A docs site is meant to be visited by everyone, so just running it locally isn't enough. Next, we can deploy it online.

A simple deployment option is to use Leapcell. It's a web app hosting platform that can host projects in various languages and frameworks, including FastAPI, of course.

Follow the steps below:

1.Register an account on the website.

2.Commit your project to GitHub. You can refer to GitHub's official documentation for the steps. Leapcell will pull the code from your GitHub repository later.

3.Click "Create Service" on the Leapcell page.

4.After choosing your FastAPI repo, you'll see Leapcell has auto-populated the necessary configurations.

Summary

Congratulations! You have successfully taken the first step: setting up a FastAPI project and implementing basic HTML template rendering.

If you've used other documentation sites, you've probably noticed that their content isn't manually written in HTML. You just write Markdown, and the web pages are generated automatically.

In the next article, we will implement this core feature: dynamically reading a real Markdown file (e.g., docs/hello.md), parsing it into HTML, and injecting it into our web template.

Read other articles in this series

Related Posts:

Build Your Own Forum with FastAPI: Step 10 - Categories

Leapcell — Tue, 04 Nov 2025 15:22:27 +0000

In the previous article, we added an image upload feature to our forum, enriching the content of our posts.

Currently, all posts are crowded onto the same homepage feed. As the forum's content grows, this becomes very disorganized. Users might only be interested in specific topics but are distracted by unrelated content.

To solve this, in this article, we will introduce a Categories feature. We will create various boards (e.g., "Technical Discussion," "General Chat"), allowing users to select a category when posting and to browse posts by category.

Step 1: Update Database Models

We need a new table categories to store category information, and we need to add a foreign key in the posts table to link it.

Open models.py, add the Category model, and update the Post model.

models.py (Updated)

from sqlalchemy import Column, Integer, String, ForeignKey, Boolean
from sqlalchemy.orm import relationship
from sqlalchemy.dialects.postgresql import TSVECTOR
from database import Base

# ... (User and Comment models remain unchanged) ...

class Post(Base):
    __tablename__ = "posts"

    id = Column(Integer, primary_key=True, index=True)
    title = Column(String, index=True)
    content = Column(String)
    owner_id = Column(Integer, ForeignKey("users.id"))
    image_url = Column(String, nullable=True)

    # --- New field ---
    category_id = Column(Integer, ForeignKey("categories.id"), nullable=False)
    # ---------------

    owner = relationship("User", back_populates="posts")
    comments = relationship("Comment", back_populates="post", cascade="all, delete-orphan")
    search_vector = Column(TSVECTOR, nullable=True)

    # --- New relationship ---
    category = relationship("Category", back_populates="posts")
    # ---------------

class Category(Base):
    __tablename__ = "categories"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, unique=True, index=True, nullable=False)
    description = Column(String, nullable=True)

    posts = relationship("Post", back_populates="category")

The main changes in this step are:

Created a new Category model.
Added category_id as a foreign key in the Post model.
Established a relationship between Post and Category, allowing us to access category info via post.category or all posts in a category via category.posts.

Step 2: Update Database Table Structure

Next, we need to actually create this table in the database and modify the posts table.

Create the `categories` table

CREATE TABLE categories (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) UNIQUE NOT NULL,
    description TEXT
);

Create default categories

To make the categories usable immediately, let's manually create two:

INSERT INTO categories (name, description) VALUES
('Technical', 'Discuss FastAPI, Python, databases, and other technical topics'),
('General', 'Share daily life, hobbies, etc.');

Modify the `posts` table

-- Add category_id column
ALTER TABLE posts ADD COLUMN category_id INTEGER;

-- Add foreign key constraint
ALTER TABLE posts ADD CONSTRAINT fk_category
    FOREIGN KEY(category_id) REFERENCES categories(id);

Handle existing posts

For existing data in the posts table, we need to assign them a default category_id.

-- Update all existing posts to the 'General Chat' category (assuming its id is 2)
UPDATE posts SET category_id = 2 WHERE category_id IS NULL;

Set to Not Null

Finally, to ensure data integrity, we will set the category_id column to NOT NULL.

ALTER TABLE posts ALTER COLUMN category_id SET NOT NULL;

If your database was created using Leapcell,

you can execute these SQL statements directly in its web-based operation panel.

Step 3: Update Post Creation Logic

Now when users create a post, they must specify a category. We need to modify the create_post route to accept category_id.

main.py (Update create_post route)

# ... (Previous imports) ...

@app.post("/api/posts")
async def create_post(
    title: str = Form(...),
    content: str = Form(...),
    category_id: int = Form(...),  # Added category_id
    image: Optional[UploadFile] = File(None),
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    # ... (Other logic remains unchanged) ...

    # Include category_id when creating the Post object
    new_post = models.Post(
        title=title,
        content=content,
        owner_id=current_user.id,
        image_url=image_url,
        category_id=category_id  # Save the category ID
    )

    db.add(new_post)
    await db.commit()
    await db.refresh(new_post)

    # 3. Redirect to the category page after posting, not the homepage
    return RedirectResponse(url=f"/categories/{category_id}", status_code=status.HTTP_303_SEE_OTHER)

Step 4: Implement Browsing by Category

We will no longer use /posts as the only post list page. Instead, we'll create a new route GET /categories/{category_id} to display posts from a specific category.

We will also modify the existing GET /posts route to serve as an "All Posts" aggregation page.

main.py (Add/modify routes)

# ... (Previous imports) ...
from sqlalchemy.orm import selectinload

# ... (Dependencies, etc.) ...

# Helper function: get all categories from the database
async def get_all_categories(db: AsyncSession):
    result = await db.execute(select(models.Category).order_by(models.Category.id))
    return result.scalars().all()

@app.get("/posts", response_class=HTMLResponse)
async def view_posts(
    request: Request,
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    # Query all categories (for navigation)
    categories = await get_all_categories(db)

    # Query all posts
    stmt = (
        select(models.Post)
        .options(selectinload(models.Post.owner), selectinload(models.Post.category))
        .order_by(desc(models.Post.id))
    )
    result = await db.execute(stmt)
    posts = result.scalars().all()

    return templates.TemplateResponse("posts.html", {
        "request": request,
        "posts": posts,
        "categories": categories,
        "current_user": current_user,
        "current_category": None  # Mark that we are not in any specific category
    })

# --- New Route ---
@app.get("/categories/{category_id}", response_class=HTMLResponse)
async def view_posts_by_category(
    request: Request,
    category_id: int,
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    # Query all categories (for navigation)
    categories = await get_all_categories(db)

    # Query the current category
    category_result = await db.execute(select(models.Category).where(models.Category.id == category_id))
    current_category = category_result.scalar_one_or_none()

    if not current_category:
        raise HTTPException(status_code=404, detail="Category not found")

    # Query posts in this category
    stmt = (
        select(models.Post)
        .where(models.Post.category_id == category_id)
        .options(selectinload(models.Post.owner), selectinload(models.Post.category))
        .order_by(desc(models.Post.id))
    )
    result = await db.execute(stmt)
    posts = result.scalars().all()

    return templates.TemplateResponse("posts.html", {
        "request": request,
        "posts": posts,
        "categories": categories,
        "current_user": current_user,
        "current_category": current_category # Pass the current category information
    })

# ... (Other routes) ...

@app.get("/posts/{post_id}", response_class=HTMLResponse)
async def view_post_detail(
    request: Request,
    post_id: int,
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    # When querying a post, also preload category info
    result = await db.execute(
        select(models.Post)
        .where(models.Post.id == post_id)
        .options(selectinload(models.Post.owner), selectinload(models.Post.category))
    )
    post = result.scalar_one_or_none()
    # ... (Subsequent comment query logic, etc., remains unchanged) ...

We added a new route GET /categories/{category_id} which reuses the posts.html template but only passes in posts for that category. We also modified GET /posts and GET /posts/{post_id} to ensure they correctly load and pass category information.

Step 5: Update Frontend Templates

Finally, we need to update the templates to display category navigation, allow selecting a category when posting, and show which category a post belongs to.

templates/posts.html (Updated)

<!DOCTYPE html>
<html>
  <head>
    <style>
        /* ... (Existing styles) ... */
        .category-nav { margin-top: 20px; margin-bottom: 20px; }
        .category-nav a { margin-right: 15px; text-decoration: none; }
        .category-nav a.active { font-weight: bold; }
        .post-category { font-size: 0.9em; color: #888; }
    </style>
  </head>
  <body>
    <div class="category-nav">
        <strong>Categories:</strong>
        <a href="/posts" class="{{ 'active' if not current_category else '' }}">All</a>
        {% for category in categories %}
            <a href="/categories/{{ category.id }}" 
               class="{{ 'active' if current_category and current_category.id == category.id else '' }}">
                {{ category.name }}
            </a>
        {% endfor %}
    </div>

    {% if current_user and not current_user.is_banned %}
    <h2>
        Post a new thread {% if current_category %}in {{ current_category.name }} {% endif %}
    </h2>
    <form action="/api/posts" method="post" enctype="multipart/form-data">
      <input type="text" name="title" placeholder="Post Title" required /><br />
      <textarea name="content" rows="4" placeholder="Post Content" required></textarea><br />

      <label for="category">Select Category:</label>
      <select name="category_id" id="category" required>
        {% for category in categories %}
            <option value="{{ category.id }}"
                    {{ 'selected' if current_category and current_category.id == category.id else '' }}>
                {{ category.name }}
            </option>
        {% endfor %}
      </select>
      <br /><br />

      <label for="image">Upload Image (Optional, JPEG/PNG/GIF):</label>
      <input type="file" name="image" id="image" accept="image/jpeg,image/png,image/gif" />
      <br /><br />

      <button type="submit">Post</button>
    </form>
    {% elif current_user and current_user.is_banned %}
    {% else %}
    {% endif %}

    <hr />
    <h2>
        Post List - {{ current_category.name if current_category else "All Posts" }}
    </h2>

    {% for post in posts %}
    <div class="post-item">
      <a href="/posts/{{ post.id }}"><h3>{{ post.title }}</h3></a>

      <p>{{ post.content }}</p>
      <small>
          Author: {{ post.owner.username if post.owner else 'Unknown' }} | 
          Category: <a href="/categories/{{ post.category.id }}">{{ post.category.name }}</a>
      </small>

      </div>
    {% endfor %}
  </body>
</html>

templates/post_detail.html (Updated)

On the post detail page, we also add the category information.

...
<body>
    <div class="post-container">
      <h1>{{ post.title }}</h1>

      <p>{{ post.content }}</p>
      <small>
          Author: {{ post.owner.username }} | 
          Category: <a href="/categories/{{ post.category.id }}">{{ post.category.name }}</a>
      </small>
    </div>
...

Run and Verify

Restart your uvicorn server:

uvicorn main:app --reload

Visit http://127.0.0.1:8000/.

You will see the new category navigation bar at the top ("All," "Technical," "General").

The "Post a new thread" form now has a new required "Select Category" dropdown.

In the post list, each post will show which category it belongs to.

Try clicking a category (e.g., "General"). The page will redirect to /categories/2, displaying only posts from that category, and the "Select Category" dropdown in the form will default to "General."

Conclusion

By adding the Category model and updating our routes and templates, we have successfully implemented a categories feature for our forum. It is now more convenient for users to find and browse the forum's content.

Read other articles in this series

Related Posts:

Build Your Own Forum with FastAPI: Step 9 - Upload Images

Leapcell — Sun, 02 Nov 2025 06:44:21 +0000

In the previous article, we used PostgreSQL's built-in full-text search feature to enable post searching in our forum.

Next, we'll continue to enrich our site's functionality by adding support for uploading images in posts.

The process for uploading images is as follows:

The user selects an image file and submits it.
After FastAPI receives the data, it forwards the image file to a dedicated object storage service, such as S3.

Why not store it directly on the server?

While this is convenient, it has several problems:

You need to maintain persistent storage for the images. This means ensuring that image files are not lost every time you deploy the application.
Serving images from the server will consume the server's expensive bandwidth and computing resources. Handling this with object storage doesn't use server compute resources, and the bandwidth is much cheaper.

That's why we need to use an external object storage service like S3.

Step 1: Prepare an S3 Storage Bucket

You'll need an S3-compatible storage service. You can choose:

Leapcell. Leapcell is a platform that provides all-in-one backend services, allowing you to build websites, deploy databases, and it also includes S3-compatible object storage.
Amazon S3 (AWS official service)
Other cloud providers, as long as they are marked as S3-compatible.

Next, we'll use Leapcell as an example.

Fill in a name to create the Object Storage.

On the Object Storage details page, you can see the Endpoint, Access Key ID, and Secret Access Key, which are the parameters used for connection. We will use them in our backend configuration later.

The interface also provides a very convenient UI, allowing you to upload and manage files directly in the browser.

Step 2: Install Dependencies

We will use boto3, which is the official AWS Python SDK and is also fully compatible with all S3-protocol services.

pip install boto3

Step 3: Add Configuration

Create a config.py in the project root directory to manage all object storage configurations centrally:

config.py

# S3 Storage Configuration
# Please replace with your own S3 information
S3_ENDPOINT_URL = "https.objstorage.leapcell.io"
S3_ACCESS_KEY = "YOUR_ACCESS_KEY"
S3_SECRET_KEY = "YOUR_SECRET_KEY"
S3_BUCKET_NAME = "your-bucket-name"
S3_PUBLIC_URL = "https://your-bucket-name.leapcellobj.com"

Step 4: Create S3 Upload Utility

To make the logic clearer, we'll create a new file s3_utils.py specifically for handling file uploads.

s3_utils.py

import boto3
import uuid
import config

# Initialize the S3 client
s3_client = boto3.client(
    's3',
    endpoint_url=config.S3_ENDPOINT_URL,
    aws_access_key_id=config.S3_ACCESS_KEY,
    aws_secret_access_key=config.S3_SECRET_KEY
)

def upload_file_to_s3(file_bytes: bytes, bucket_name: str, content_type: str, extension: str) -> str:
    """
    Uploads a binary file stream to S3
    :param file_bytes: The binary content of the file
    :param bucket_name: The bucket name
    :param content_type: The MimeType of the file
    :param extension: The file extension
    :return: The public URL of the file
    """

    # Generate a unique filename
    file_name = f"uploads/{uuid.uuid4()}.{extension}"

    try:
        s3_client.put_object(
            Body=file_bytes,
            Bucket=bucket_name,
            Key=file_name,
            ContentType=content_type,
        )

        # Construct and return the public URL
        public_url = f"{config.S3_PUBLIC_URL}/{file_name}"
        return public_url

    except Exception as e:
        print(f"S3 upload failed: {e}")
        return None

Step 5: Update Database Model

We need to add a field to the posts table to store the uploaded image URL.

Open models.py and modify the Post model:

models.py (Update Post model)

from sqlalchemy import Column, Integer, String, ForeignKey, Boolean
# ... (Other imports)

class Post(Base):
    __tablename__ = "posts"

    id = Column(Integer, primary_key=True, index=True)
    title = Column(String, index=True)
    content = Column(String)
    owner_id = Column(Integer, ForeignKey("users.id"))

    # --- New Field ---
    image_url = Column(String, nullable=True)
    # ---------------

    owner = relationship("User", back_populates="posts")
    comments = relationship("Comment", back_populates="post", cascade="all, delete-orphan")
    search_vector = Column(TSVECTOR, nullable=True)

We also need to update our database table structure. The corresponding SQL statement is:

ALTER TABLE posts ADD COLUMN image_url VARCHAR(512);

If your database was created using Leapcell,

you can execute these SQL statements directly in its web-based operation panel.

Step 6: Refactor the Backend Route

Next, let's modify the create_post route in main.py to accept file uploads.

main.py (Update create_post route)

# ... (Previous imports) ...
from fastapi import File, UploadFile
import s3_utils  # Import the utility we just created
import config    # Import the configuration
import asyncio   # Import asyncio

# ... (app, templates, dependencies, etc., remain unchanged) ...

@app.post("/api/posts")
async def create_post(
    title: str = Form(...),
    content: str = Form(...),
    image: Optional[UploadFile] = File(None),  # 1. Accept the image file
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    if not current_user:
        return RedirectResponse(url="/login", status_code=status.HTTP_302_FOUND)

    if current_user.is_banned:
        raise HTTPException(status_code=403, detail="You are banned and cannot create posts.")

    image_url = None

    # 2. Process the image upload
    if image and image.filename:
        # Check file type
        if image.content_type not in ["image/jpeg", "image/png", "image/gif"]:
            raise HTTPException(status_code=400, detail="Invalid file type. Only JPEG, PNG, GIF are allowed.")

        # Read file content
        file_bytes = await image.read()

        # Get file extension
        extension = image.filename.split('.')[-1]

        # 3. Use asyncio.to_thread to run the blocking S3 upload in a background thread
        # Boto3 (s3_client.put_object) is a blocking I/O operation
        # in
        image_url = await asyncio.to_thread(
            s3_utils.upload_file_to_s3,
            file_bytes,
            config.S3_BUCKET_NAME,
            image.content_type,
            extension
        )

        if not image_url:
            raise HTTPException(status_code=500, detail="Image upload failed.")

    # 4. Create the Post object, including the image_url
    new_post = models.Post(
        title=title,
        content=content,
        owner_id=current_user.id,
        image_url=image_url  # Save the URL
    )

    db.add(new_post)
    await db.commit()
    await db.refresh(new_post)
    return RedirectResponse(url="/posts", status_code=status.HTTP_303_SEE_OTHER)

# ... (All other routes remain unchanged) ...

The main changes are:

The create_post parameters now include image: Optional[UploadFile] = File(None).
Read the content of the image parameter (await image.read()) and call s3_utils.upload_file_to_s3 to upload the image to object storage.
Finally, when creating the models.Post object, save the image_url returned from the previous step to the database.

Step 7: Update Frontend Templates

Finally, we need to update our frontend pages to add the file upload field and display the images.

templates/posts.html (Updated)

... (head and style remain unchanged) ...
<body>
    <header>
        ... (header content remains unchanged) ...
    </header>
    <form action="/search" method="GET" style="display: flex;">
        ... (search form remains unchanged) ...
    </form>

    {% if current_user and not current_user.is_banned %}
    <h2>Create New Post</h2>
    <form action="/api/posts" method="post" enctype="multipart/form-data">
        <input type="text" name="title" placeholder="Post Title" required /><br />
        <textarea name="content" rows="4" placeholder="Post Content" required></textarea><br />

        <label for="image">Upload Image (Optional, JPE/PNG/GIF):</label>
        <input type="file" name="image" id="image" accept="image/jpeg,image/png,image/gif" />
        <br /><br />

        <button type="submit">Post</button>
    </form>
    {% elif current_user and current_user.is_banned %}
        ... (banned message) ...
    {% else %}
        ... (login prompt) ...
    {% endif %}

    <hr />
    <h2>Post List</h2>

    {% for post in posts %}
    <div class="post-item">
        <a href="/posts/{{ post.id }}"><h3>{{ post.title }}</h3></a>

        {% if post.image_url %}
        <img src="{{ post.image_url }}" alt="{{ post.title }}" style="max-width: 400px; height: auto; margin-bottom: 10px;" />
        {% endif %}

        <p>{{ post.content }}</p>
        <small>Author: {{ post.owner.username if post.owner else 'Unknown' }}</small>

        {% if current_user and post.owner_id == current_user.id %}
            ... (edit link) ...
        {% endif %}
    </div>
    {% endfor %}
</body>
</html>

templates/post_detail.html (Updated)

... (head and style remain unchanged) ...
<body>
    <div class="post-container">
        <h1>{{ post.title }}</h1>

        {% if post.image_url %}
        <img src="{{ post.image_url }}" alt="{{ post.title }}" style="max-width: 600px; height: auto; margin-bottom: 10px;" />
        {% endif %}

        <p>{{ post.content }}</p>
        <small>Author: {{ post.owner.username }}</small>
    </div>

    ... (comment form and comment section remain unchanged) ...
</body>
</html>

Run and Verify

Restart your uvicorn server:

uvicorn main:app --reload

Visit http://127.0.0.1:8000.

You will see a file selection button in the "Create New Post" form.

Try to publish a new post and attach an image. After submitting, you will see the image you uploaded in the post.

Conclusion

Using object storage, you've successfully added image upload functionality to the forum.

Currently, all posts are crowded onto the same page. This will become very chaotic as the forum's content grows.

In the next article, we will add Categories (sub-forums) to the forum, allowing posts to be organized by different topics, making the forum more structured.

Read other articles in this series

Related Posts:

Build Your Own Forum with FastAPI: Step 8 - Full Text Search

Leapcell — Fri, 31 Oct 2025 10:40:59 +0000

In the previous article, we implemented a basic permissions system for our forum, supporting "administrator" and "user banning" capabilities, laying the groundwork for a healthy community.

As the forum accumulates more content, users might find it difficult to locate old posts they are interested in. A new requirement is emerging: shouldn't there be a search function to help users quickly find the articles they want to read?

In this article, we are going to add a full-text search feature to our forum.

If you have some knowledge of SQL, you might be thinking: can't we just use a LIKE '%keyword%' query to implement search? For simple scenarios, this is indeed possible. But LIKE queries perform extremely poorly when dealing with large amounts of text and cannot understand linguistic complexities (for example, searching for "create" won't match "creating").

Therefore, we will adopt a more professional and efficient solution: using PostgreSQL's built-in Full-Text Search (FTS) feature. It's not only fast but also supports stemming, ignoring stop words, and sorting by relevance, providing search capabilities far superior to LIKE.

Step 1: Database Search Infrastructure (SQL)

To use PostgreSQL's FTS feature, we first need to make some modifications to our posts table: we'll create a special column specifically for storing optimized, high-speed searchable text data.

Add the tsvector Column

We will add a new column named search_vector of type tsvector to the posts table. Its purpose is like a dictionary, breaking down the post's title and content into individual words (lexemes) and processing them.

ALTER TABLE posts ADD COLUMN "search_vector" tsvector;

Use a Trigger to Automatically Update the tsvector Column

The search_vector column doesn't contain content by itself; we need to convert the title and content into the tsvector format and write it into this column.

Nobody wants to manually update the search_vector column every time a post is created or updated. The best way is to have the database do this work automatically using a trigger.

First, let's create a function. This function's job is to concatenate the title and content and convert them into the tsvector format.

CREATE OR REPLACE FUNCTION update_post_search_vector()
RETURNS TRIGGER AS $$
BEGIN
    NEW.search_vector :=
        setweight(to_tsvector('english', coalesce(NEW.title, '')), 'A') ||
        setweight(to_tsvector('english', coalesce(NEW.content, '')), 'B');
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

The setweight function allows us to set different weights for text from different fields. Here, we are setting the weight for the title ('A') higher than for the content ('B'). This means that in the search results, posts with the keyword in the title will be ranked higher.

Next, create a trigger that will automatically call the function we just created every time a new post is inserted (INSERT) or updated (UPDATE).

CREATE TRIGGER post_search_vector_update
BEFORE INSERT OR UPDATE ON posts
FOR EACH ROW EXECUTE FUNCTION update_post_search_vector();

Create the Search Index

To ensure search speed, the final step is to create a GIN (Generalized Inverted Index) index on the search_vector column.

CREATE INDEX post_search_vector_idx ON posts USING gin(search_vector);

Step 2: Backfill Existing Data

It's important to note that the trigger we created only works for posts created or modified in the future. For posts that already exist in the database, their search_vector field is still NULL.

We need to run a one-time UPDATE statement to generate search vectors for all existing posts:

-- Backfill search_vector for all existing posts
UPDATE posts SET search_vector =
    setweight(to_tsvector('english', coalesce(title, '')), 'A') ||
    setweight(to_tsvector('english', coalesce(content, '')), 'B');

If your database was created using Leapcell,

you can execute these SQL statements directly in its web-based operation panel.

Step 3: Create the Search Results Page

We need a new HTML page to display the search results.

In the templates folder, create a new file named search_results.html. This page is very similar to posts.html, but it will additionally display the user's search query.

templates/search_results.html

<!DOCTYPE html>
<html>
  <head>
    <title>Search Results - My FastAPI Forum</title>
    <style>
      /* (Copy all styles from templates/posts.html) */
      body {
        font-family: sans-serif;
        margin: 2em;
      }
      input,
      textarea {
        width: 100%;
        padding: 8px;
        margin-bottom: 10px;
        box-sizing: border-box;
      }
      button {
        padding: 10px 15px;
        background-color: #007bff;
        color: white;
        border: none;
        cursor: pointer;
      }
      header {
        display: flex;
        justify-content: space-between;
        align-items: center;
      }
      .post-item {
        border: 1px solid #ccc;
        padding: 10px;
        margin-bottom: 10px;
      }
      /* (End of copied styles) */
    </style>
  </head>
  <body>
    <header>
      <h1><a href="/posts" style="text-decoration: none; color: black;">Welcome to my Forum</a></h1>
      <div class="auth-links">
        {% if current_user %}
        <span>Welcome, {{ current_user.username }}!</span>
        {% if current_user.is_admin %}
        <a href="/admin" style="color: red; font-weight: bold;">[Admin Panel]</a>
        {% endif %}
        <a href="/logout">Logout</a>
        {% else %}
        <a href="/login">Login</a> |
        <a href="/register">Register</a>
        {% endif %}
      </div>
    </header>
    <form action="/search" method="GET" style="display: inline-block;">
      <input type="search" name="q" placeholder="Search posts..." value="{{ query | escape }}" />
      <button type="submit">Search</button>
    </form>

    <hr />
    <h2>Search Results: "{{ query | escape }}"</h2>

    {% if posts %} {% for post in posts %}
    <div class="post-item">
      <a href="/posts/{{ post.id }}"><h3>{{ post.title }}</h3></a>
      <p>{{ post.content }}</p>
      <small>Author: {{ post.owner.username if post.owner else 'Unknown' }}</small>
    </div>
    {% endfor %} {% else %}
    <p>No posts found matching "{{ query | escape }}". Please try different keywords.</p>
    {% endif %}
  </body>
</html>

Note that we also placed {{ query }} in the search box's value attribute. This way, after searching, the search box will retain the user's search term.

Step 4: Implement the Search Backend Route

With the database and frontend page ready, we will now add the backend logic in main.py to handle search requests.

First, update the Post model:

models.py

# ... (previous imports) ...
from sqlalchemy.dialects.postgresql import TSVECTOR

class Post(Base):
    __tablename__ = "posts"

    # ... (other existing fields)

    # --- New field ---
    search_vector = Column(TSVECTOR, nullable=True)

Next, modify main.py:

main.py (Add new route and imports)

# ... (previous imports) ...
from fastapi import Query
from sqlalchemy import func, desc
from sqlalchemy.orm import selectinload

# ... (app, templates, dependencies get_db, get_current_user, get_admin_user remain unchanged) ...

# --- Routes ---

# ... (previous routes /, /posts, /api/posts, /admin, etc. remain unchanged) ...

# 1. Add new search route
@app.get("/search", response_class=HTMLResponse)
async def search_posts(
    request: Request,
    q: Optional[str] = Query(None),  # Get 'q' parameter from URL query string
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    posts = []

    if q and q.strip():
        # 1. Process search term: replace spaces with '&' (AND operator)
        processed_query = " & ".join(q.strip().split())

        # 2. Build FTS query
        # func.to_tsquery('english', ...) converts the query string to tsquery type
        # models.Post.search_vector.op('@@')(...) is the FTS match operator
        # func.ts_rank(...) calculates the relevance rank
        stmt = (
            select(models.Post)
            .where(models.Post.search_vector.op('@@')(func.to_tsquery('english', processed_query)))
            .order_by(desc(func.ts_rank(
                models.Post.search_vector,
                func.to_tsquery('english', processed_query)
            )))
            .options(selectinload(models.Post.owner))  # Preload owner information
        )

        result = await db.execute(stmt)
        posts = result.scalars().all()

    return templates.TemplateResponse("search_results.html", {
        "request": request,
        "posts": posts,
        "query": q if q else "",
        "current_user": current_user
    })


# ... (subsequent routes /posts/{post_id}, /posts/{post_id}/comments, etc. remain unchanged) ...

The new GET /search route primarily does these things:

Reads the q parameter (search term), replaces spaces in it with & so that the query will match all keywords.
Uses func.to_tsquery, func.ts_rank, and op('@@') to build the specialized FTS query, and sorts the results by relevance (ts_rank) in descending order.
Renders the search_results.html template with the query results.

Step 5: Add the Search Box to the Homepage

Finally, we need to provide a search entry point for users on the forum's homepage.

Modify templates/posts.html to add the search form in the <header>.

templates/posts.html (Update header)

... (head and style remain unchanged) ...
<body>
    <header>
      <h1><a href="/posts" style="text-decoration: none; color: black;">Welcome to My Forum</a></h1>
      <div class="auth-links">
        {% if current_user %}
        <span>Welcome, {{ current_user.username }}!</span>
        {% if current_user.is_admin %}
        <a href="/admin" style="color: red; font-weight: bold;">[Admin Panel]</a>
        {% endif %}
        <a href="/logout">Logout</a>
        {% else %}
        <a href="/login">Login</a> |
        <a href="/register">Register</a>
        {% endif %}
      </div>
    </header>
    <form action="/search" method="GET" style="display: inline-block;">
      <input type="search" name="q" placeholder="Search posts..." />
      <button type="submit">Search</button>
    </form>

    ... (rest of the page remains unchanged) ...
</body>
</html>

We also added an <a> link to the <h1> tag, allowing users to click the title to return to the homepage.

Run and Verify

The feature is now implemented. Restart your uvicorn server:

uvicorn main:app --reload

Open your browser and visit http://127.0.0.1:8000.

You will see a new search box next to the title at the top of the page.

Enter any word in the search box and press Enter. The page will redirect to the /search route and display the relevant posts.

Summary

By leveraging PostgreSQL FTS, we've added a powerful and professional full-text search feature to our forum. Users can now easily find past posts.

Next, let's continue to enrich our forum's features. You may have noticed that posts can only be plain text and cannot include images.

In the next article, we will implement: allowing users to upload images when creating a post.

Read other articles in this series

Related Posts:

Build Your Own Forum with FastAPI: Step 7 - Permissions

Leapcell — Sun, 26 Oct 2025 14:04:28 +0000

In the previous article, we implemented comments and replies for our forum, which greatly enhanced community interaction.

Interaction, however, can inevitably lead to conflict. As interaction increases, community management becomes a problem we must face. What if someone posts malicious content?

In this article, we will introduce a basic permission management system. We will establish an "Admin" role and give administrators the ability to "ban" users to maintain community order.

Step 1: Update the Database Model

We need to add two fields to the user table (users): one to identify who is an admin, and another to mark who has been "banned."

Open models.py and modify the User model:

models.py (Update User model)

from sqlalchemy import Column, Integer, String, ForeignKey, Boolean
from sqlalchemy.orm import relationship
from database import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    username = Column(String, unique=True, index=True)
    hashed_password = Column(String)

    # --- New fields ---
    is_admin = Column(Boolean, default=False)
    is_banned = Column(Boolean, default=False)
    # ---------------

    posts = relationship("Post", back_populates="owner", cascade="all, delete-orphan")
    comments = relationship("Comment", back_populates="owner", cascade="all, delete-orphan")

# ... Post and Comment models remain unchanged ...

We've added two fields: is_admin and is_banned. Both are set to default=False to avoid affecting existing users.

After updating the model, you need to manually update your database table structure. The corresponding SQL statements are as follows:

-- Add is_admin column to users table
ALTER TABLE users ADD COLUMN is_admin BOOLEAN DEFAULT FALSE;

-- Add is_banned column to users table
ALTER TABLE users ADD COLUMN is_banned BOOLEAN DEFAULT FALSE;

If your database was created using Leapcell,

you can execute these SQL statements directly in its web-based operation panel.

Step 2: Manually Appoint an Administrator

Our forum doesn't have an "admin backend" to appoint administrators yet. Since creating an admin is an infrequent requirement, we can just operate the database directly to manually set your user as an admin.

Execute the following command in your database:

-- Set the user with username 'your_username' as an admin
UPDATE users SET is_admin = TRUE WHERE username = 'your_username';

Remember to replace your_username with the username you registered with.

Step 3: Create the Admin Panel Page

We need a page that only administrators can access, which will display all users and provide action buttons.

In the templates folder, create a new file named admin.html.

templates/admin.html

<!DOCTYPE html>
<html>
  <head>
    <title>Admin Panel - My FastAPI Forum</title>
    <style>
      body {
        font-family: sans-serif;
        margin: 2em;
      }
      li {
        margin-bottom: 10px;
      }
      button {
        margin-left: 10px;
        padding: 5px;
      }
    </style>
  </head>
  <body>
    <h1>Admin Panel - User Management</h1>
    <a href="/posts">Back to Home</a>
    <hr />
    <ul>
      {% for user in users %}
      <li>
        <strong>{{ user.username }}</strong>
        <span>(Admin: {{ user.is_admin }}, Banned: {{ user.is_banned }})</span>

        {% if not user.is_admin %} {% if user.is_banned %}
        <form action="/admin/unban/{{ user.id }}" method="post" style="display: inline;">
          <button type="submit" style="background-color: #28a745; color: white;">Unban</button>
        </form>
        {% else %}
        <form action="/admin/ban/{{ user.id }}" method="post" style="display: inline;">
          <button type="submit" style="background-color: #dc3545; color: white;">Ban</button>
        </form>
        {% endif %} {% endif %}
      </li>
      {% endfor %}
    </ul>
  </body>
</html>

This page iterates through all users. If a user is not an admin, a "Ban" or "Unban" button will be displayed next to them. These buttons will point to the API routes we are about to create via a POST request.

Step 4: Implement the Admin Backend Routes

Now, we need to add new routes in main.py to handle the admin panel logic.

main.py (Add new routes and dependency)

# ... (Previous imports remain unchanged) ...

# --- Dependencies ---

# ... (get_current_user remains unchanged) ...

# 1. Add a new dependency to verify admin permissions
async def get_admin_user(
    current_user: Optional[models.User] = Depends(get_current_user)
) -> models.User:
    if not current_user:
        raise HTTPException(
            status_code=status.HTTP_302_FOUND,
            detail="Not authenticated",
            headers={"Location": "/login"}
        )
    if not current_user.is_admin:
        # If not an admin, raise a 403 error
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="You do not have permission to access this resource."
        )
    return current_user

# --- Routes ---

# ... (Previous routes /, /posts, /api/posts, etc., remain unchanged) ...

# 2. Add admin panel route
@app.get("/admin", response_class=HTMLResponse)
async def view_admin_panel(
    request: Request,
    db: AsyncSession = Depends(get_db),
    admin_user: models.User = Depends(get_admin_user)
):
    # Query all users
    result = await db.execute(select(models.User).order_by(models.User.id))
    users = result.scalars().all()

    return templates.TemplateResponse("admin.html", {
        "request": request,
        "users": users
    })

# 3. Ban user route
@app.post("/admin/ban/{user_id}")
async def ban_user(
    user_id: int,
    db: AsyncSession = Depends(get_db),
    admin_user: models.User = Depends(get_admin_user)
):
    result = await db.execute(select(models.User).where(models.User.id == user_id))
    user = result.scalar_one_or_none()

    if not user:
        raise HTTPException(status_code=404, detail="User not found")

    # Admins cannot ban other admins
    if user.is_admin:
        raise HTTPException(status_code=403, detail="Cannot ban an admin")

    user.is_banned = True
    await db.commit()
    return RedirectResponse(url="/admin", status_code=status.HTTP_303_SEE_OTHER)

# 4. Unban user route
@app.post("/admin/unban/{user_id}")
async def unban_user(
    user_id: int,
    db: AsyncSession = Depends(get_db),
    admin_user: models.User = Depends(get_admin_user)
):
    result = await db.execute(select(models.User).where(models.User.id == user_id))
    user = result.scalar_one_or_none()

    if not user:
        raise HTTPException(status_code=404, detail="User not found")

    user.is_banned = False
    await db.commit()
    return RedirectResponse(url="/admin", status_code=status.HTTP_303_SEE_OTHER)

# ... (Subsequent routes /posts/{post_id}, /posts/{post_id}/comments, etc., remain unchanged) ...

This includes these main changes:

Created a new dependency get_admin_user, which is based on get_current_user and additionally checks if current_user.is_admin is True.
Created the GET /admin route, which queries all users and renders the admin.html template. This route is protected by Depends(get_admin_user) to ensure only admins can access it.
Created POST /admin/ban/{user_id} and POST /admin/unban/{user_id} routes to ban/unban specific users.

Step 5: Enforce the Ban (Prevent Posting)

A user can now be marked as "banned," but their actions are not yet affected. A banned user can still create posts and comments.

We need to modify the create_post and create_comment routes to check the user's status before performing the action.

main.py (Update create_post and create_comment)

# ... (Previous code) ...

@app.post("/api/posts")
async def create_post(
    title: str = Form(...),
    content: str = Form(...),
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    if not current_user:
        return RedirectResponse(url="/login", status_code=status.HTTP_302_FOUND)

    # --- Add check ---
    if current_user.is_banned:
        raise HTTPException(status_code=403, detail="You are banned and cannot create posts.")
    # ---------------

    new_post = models.Post(title=title, content=content, owner_id=current_user.id)
    # ... (Subsequent code remains unchanged) ...
    db.add(new_post)
    await db.commit()
    await db.refresh(new_post)
    return RedirectResponse(url="/posts", status_code=status.HTTP_303_SEE_OTHER)

# ... (Other routes) ...

@app.post("/posts/{post_id}/comments")
async def create_comment(
    post_id: int,
    content: str = Form(...),
    parent_id: Optional[int] = Form(None),
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    if not current_user:
        return RedirectResponse(url="/login", status_code=status.HTTP_302_FOUND)

    # --- Add check ---
    if current_user.is_banned:
        raise HTTPException(status_code=403, detail="You are banned and cannot create comments.")
    # ---------------

    new_comment = models.Comment(
        content=content,
        post_id=post_id,
        owner_id=current_user.id,
        parent_id=parent_id
    )
    # ... (Subsequent code remains unchanged) ...
    db.add(new_comment)
    await db.commit()
    return RedirectResponse(url=f"/posts/{post_id}", status_code=status.HTTP_303_SEE_OTHER)

# ... (Subsequent routes /posts/{post_id}/edit, /register, /login, /logout, etc., remain unchanged) ...

Now, if a banned user tries to submit a post or comment form, the backend will reject the request and return a 403 error.

Step 6: Update the Frontend UI

The backend is now secure, but from a user experience perspective, we should hide the posting and commenting forms from the frontend and give admins an entry point to the backend.

templates/posts.html (Update)

... (Header and styles remain unchanged) ...
<body>
    <header>
      <h1>Welcome to My Forum</h1>

      <div class="auth-links">
        {% if current_user %}
        <span>Welcome, {{ current_user.username }}!</span>
        {% if current_user.is_admin %}
        <a href="/admin" style="color: red; font-weight: bold;">[Admin Panel]</a>
        {% endif %}
        <a href="/logout">Logout</a>
        {% else %}
        <a href="/login">Login</a> |
        <a href="/register">Register</a>
        {% endif %}
      </div>
    </header>

    {% if current_user and not current_user.is_banned %}
    <h2>Create a New Post</h2>
    <form action="/api/posts" method="post">
      <input type="text" name="title" placeholder="Post Title" required /><br />
      <textarea name="content" rows="4" placeholder="Post Content" required></textarea><br />
      <button type="submit">Post</button>
    </form>
    {% elif current_user and current_user.is_banned %}
    <p style="color: red; font-weight: bold;">You have been banned and cannot create new posts.</p>
    {% else %}
    <p><a href="/login">Login</a> to create a new post.</p>
    {% endif %}

    <hr />
    ... (Post list section remains unchanged) ...
</body>
</html>

templates/post_detail.html (Update)

... (Header and styles remain unchanged) ...
<body>
    ... (Post detail section remains unchanged) ...
    <hr />
    <div class="comment-form">
      <h3>Post a Comment</h3>
      {% if current_user and not current_user.is_banned %}
      <form action="/posts/{{ post.id }}/comments" method="post">
        <textarea name="content" rows="4" style="width:100%;" placeholder="Write your comment..." required></textarea><br />
        <button type="submit">Submit</button>
      </form>
      {% elif current_user and current_user.is_banned %}
      <p style="color: red; font-weight: bold;">You have been banned and cannot post comments.</p>
      {% else %}
      <p><a href="/login">Log in</a> to post a comment.</p>
      {% endif %}
    </div>
    ... (Comment section remains unchanged) ...
</body>
</html>

This includes two main changes:

In the posts.html header, if the current user is an admin (current_user.is_admin), an "Admin Panel" link is displayed.
In posts.html and post_detail.html, the original {% if current_user %} condition is changed to {% if current_user and not current_user.is_banned %}, meaning only users who are not banned can see the form.

Run and Verify

Restart your uvicorn server:

uvicorn main:app --reload

Click it to go to the /admin page. You will see a list of all users and can ban other users.

Ban test_user. Switch to being logged in as test_user, and you will find that the "Create New Post" form has disappeared, replaced by a "You have been banned" message.

Conclusion

We have added basic management functions to the forum. Using the is_admin and is_banned fields, we've supported user role differentiation and permission control.

Based on this framework, you can further extend more management functions, such as shadow-banning users or prohibiting logins.

As the forum's content grows, users might find it difficult to locate old posts they are interested in.

To address this, in the next article, we will add a search function to the forum.

Read other articles in this series

Related Posts:

Build Your Own Forum with FastAPI: Step 6 - Comments and Replies

Leapcell — Sat, 25 Oct 2025 21:11:48 +0000

In the previous article, we added the post editing feature to our forum, allowing users to modify their published content.

Besides posting, interaction is essential for a forum. When users see an interesting (or controversial) post, they'll want to express their opinions.

In this article, we will add an interaction feature to our forum: implementing post comments and replies, allowing users to have discussions around posts.

Step 1: Update the Database Model

We need a new table to store comments. Furthermore, comments themselves need to support replies to form a hierarchical structure.

In models.py, add the Comment model and update the User and Post models to establish relationships.

models.py (Updated)

from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import relationship
from database import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    username = Column(String, unique=True, index=True)
    hashed_password = Column(String)

    posts = relationship("Post", back_populates="owner", cascade="all, delete-orphan")
    comments = relationship("Comment", back_populates="owner", cascade="all, delete-orphan")

class Post(Base):
    __tablename__ = "posts"

    id = Column(Integer, primary_key=True, index=True)
    title = Column(String, index=True)
    content = Column(String)
    owner_id = Column(Integer, ForeignKey("users.id"))

    owner = relationship("User", back_populates="posts")
    comments = relationship("Comment", back_populates="post", cascade="all, delete-orphan")

class Comment(Base):
    __tablename__ = "comments"

    id = Column(Integer, primary_key=True, index=True)
    content = Column(String, nullable=False)
    post_id = Column(Integer, ForeignKey("posts.id"))
    owner_id = Column(Integer, ForeignKey("users.id"))
    parent_id = Column(Integer, ForeignKey("comments.id"), nullable=True)

    owner = relationship("User", back_populates="comments")
    post = relationship("Post", back_populates="comments")

    # Self-referencing relationship for replies
    parent = relationship("Comment", back_populates="replies", remote_side=[id])
    replies = relationship("Comment", back_populates="parent", cascade="all, delete-orphan")

Here are the main changes we made:

Created the Comment model, linking it to posts and users via post_id and owner_id, respectively. The parent_id field points to the id of another comment. If it's NULL, it's a top-level comment; otherwise, it's a reply.
Updated the User and Post models, adding a relationship to Comment. cascade="all, delete-orphan" ensures that when a user or post is deleted, their associated comments are also deleted.

Next, create this new table in your database. The corresponding SQL statement is as follows:

CREATE TABLE comments (
    id SERIAL PRIMARY KEY,
    content TEXT NOT NULL,
    post_id INTEGER NOT NULL,
    owner_id INTEGER NOT NULL,
    parent_id INTEGER,
    CONSTRAINT fk_post FOREIGN KEY(post_id) REFERENCES posts(id) ON DELETE CASCADE,
    CONSTRAINT fk_owner FOREIGN KEY(owner_id) REFERENCES users(id) ON DELETE CASCADE,
    CONSTRAINT fk_parent FOREIGN KEY(parent_id) REFERENCES comments(id) ON DELETE CASCADE
);

If your database was created using Leapcell,

you can execute these SQL statements directly in its web-based operation panel.

Step 2: Create the Post Detail Page and Comment Section

Currently, all posts are displayed on the homepage. To make space for a comment section, we need to create a separate detail page for each post.

First, create a new file post_detail.html in the templates folder.

templates/post_detail.html

<!DOCTYPE html>
<html>
  <head>
    <title>{{ post.title }} - My FastAPI Forum</title>
    <style>
      body {
        font-family: sans-serif;
        margin: 2em;
      }
      .post-container {
        border: 1px solid #ccc;
        padding: 20px;
        margin-bottom: 20px;
      }
      .comment-form {
        margin-top: 20px;
      }
      .comments-section {
        margin-top: 30px;
      }
      .comment {
        border-left: 3px solid #eee;
        padding-left: 15px;
        margin-bottom: 15px;
      }
      .comment .meta {
        font-size: 0.9em;
        color: #666;
      }
      .replies {
        margin-left: 30px;
      }
    </style>
  </head>
  <body>
    <div class="post-container">
      <h1>{{ post.title }}</h1>
      <p>{{ post.content }}</p>
      <small>Author: {{ post.owner.username }}</small>
    </div>

    <hr />

    <div class="comment-form">
      <h3>Post a Comment</h3>
      {% if current_user %}
      <form action="/posts/{{ post.id }}/comments" method="post">
        <textarea name="content" rows="4" style="width:100%;" placeholder="Write your comment..." required></textarea><br />
        <button type="submit">Submit</button>
      </form>
      {% else %}
      <p><a href="/login">Log in</a> to post a comment.</p>
      {% endif %}
    </div>

    <div class="comments-section">
      <h2>Comments</h2>
      {% for comment in comments %} {% if not comment.parent_id %}
      <div class="comment">
        <p>{{ comment.content }}</p>
        <p class="meta">Posted by {{ comment.owner.username }}</p>

        {% if current_user %}
        <form action="/posts/{{ post.id }}/comments" method="post" style="margin-left: 20px;">
          <input type="hidden" name="parent_id" value="{{ comment.id }}" />
          <textarea name="content" rows="2" style="width:80%;" placeholder="Reply..." required></textarea><br />
          <button type="submit">Reply</button>
        </form>
        {% endif %}

        <div class="replies">
          {% for reply in comment.replies %}
          <div class="comment">
            <p>{{ reply.content }}</p>
            <p class="meta">Replied by {{ reply.owner.username }}</p>
          </div>
          {% endfor %}
        </div>
      </div>
      {% endif %} {% endfor %}
    </div>
    <a href="/posts">Back to Home</a>
  </body>
</html>

This template includes the post's details, a form for posting new comments, and an area to display all comments. For simplicity, we are currently only displaying one level of replies.

Step 3: Implement Backend Route Logic

Next, we'll add new routes in main.py to handle displaying the post detail page and submitting comments.

main.py (Add new routes)

# ... (previous imports remain unchanged) ...
from sqlalchemy.orm import selectinload

# ... (previous code remain unchanged) ...

# --- Routes ---

# ... (previous routes /, /posts, /api/posts, etc. remain unchanged) ...

@app.get("/posts/{post_id}", response_class=HTMLResponse)
async def view_post_detail(
    request: Request,
    post_id: int,
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    # Query for the post
    result = await db.execute(select(models.Post).where(models.Post.id == post_id).options(selectinload(models.Post.owner)))
    post = result.scalar_one_or_none()

    if not post:
        raise HTTPException(status_code=404, detail="Post not found")

    # Query for comments, and preload author and reply info
    # Use selectinload to avoid N+1 queries
    comment_result = await db.execute(
        select(models.Comment)
        .where(models.Comment.post_id == post_id)
        .options(selectinload(models.Comment.owner), selectinload(models.Comment.replies).selectinload(models.Comment.owner))
        .order_by(models.Comment.id)
    )
    comments = comment_result.scalars().all()

    return templates.TemplateResponse("post_detail.html", {
        "request": request,
        "post": post,
        "comments": comments,
        "current_user": current_user
    })


@app.post("/posts/{post_id}/comments")
async def create_comment(
    post_id: int,
    content: str = Form(...),
    parent_id: Optional[int] = Form(None),
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    if not current_user:
        return RedirectResponse(url="/login", status_code=status.HTTP_302_FOUND)

    new_comment = models.Comment(
        content=content,
        post_id=post_id,
        owner_id=current_user.id,
        parent_id=parent_id
    )
    db.add(new_comment)
    await db.commit()

    return RedirectResponse(url=f"/posts/{post_id}", status_code=status.HTTP_303_SEE_OTHER)


# ... (subsequent routes /posts/{post_id}/edit, /register, /login, /logout, etc. remain unchanged) ...

We added two new routes:

GET /posts/{post_id}: Finds the post from the database based on post_id and queries for all comments related to that post. Finally, it renders the post_detail.html template, passing the post, comments, and current user information to it.
POST /posts/{post_id}/comments: This route handles the submission of comments and replies, creating a Comment object and saving it to the database. It receives content and an optional parent_id from the form. If parent_id exists, it means this is a reply.

Step 4: Add an Entry Point on the Homepage

Everything is ready, we just need an entry point from the homepage to the post detail page. Modify templates/posts.html to turn the post title into a link.

We just need to wrap <h3>{{ post.title }}</h3> with an <a> tag, linking it to /posts/{{ post.id }}.

templates/posts.html (Updated)

... (file header and stylesheet remain unchanged) ...
<body>
    ... (header and post form sections remain unchanged) ...
    <hr />
    <h2>Post List</h2>

    {% for post in posts %}
    <div style="border: 1px solid #ccc; padding: 10px; margin-bottom: 10px;">
      <a href="/posts/{{ post.id }}"><h3>{{ post.title }}</h3></a>

      <p>{{ post.content }}</p>
      <small>Author: {{ post.owner.username if post.owner else 'Unknown' }}</small>

      {% if current_user and post.owner_id == current_user.id %}
      <div style="margin-top: 10px;">
        <a href="/posts/{{ post.id }}/edit">Edit</a>
      </div>
      {% endif %}
    </div>
    {% endfor %}
</body>
</html>

Run and Verify

Restart your uvicorn server:

uvicorn main:app --reload

Visit http://127.0.0.1:8000 and log in. On the homepage, you will find that all post titles have now become clickable links.

Click on any post title, and the page will redirect to that post's detail page.

Enter content in the comment box at the bottom of the detail page and click 'Submit'. After the page refreshes, your comment will appear in the comment section.

Below the comment, there is a smaller reply box. Enter content in it and submit, and you will see a comment as a reply.

Summary

The forum now supports comment and reply features, allowing users to interact with each other.

As the forum's functionality becomes more complex, maintaining community order becomes increasingly important. How do we control what a user can do?

In the next article, we will introduce permission management. Through systems like administrators, we will ensure the healthy development of the community. For example, banning a user from speaking.

Read on our blog

Related Posts:

Build Your Own Forum with FastAPI: Step 5 - Editing Posts

Leapcell — Sat, 25 Oct 2025 02:31:35 +0000

In the previous article, we built a user system for our forum. Now, users can register, log in, and publish posts under their own identity.

However, once a post is published, it currently cannot be modified. What if you spot an error or want to add more content?

In this article, we will implement a new feature: allowing users to edit the posts they have created.

Step 1: Create the Post Edit Page

First, we need a new HTML page where users can modify the title and content of their posts. This page will be very similar to the new post form, but it will come pre-filled with the post's existing data.

In the templates folder, create a new file named edit_post.html.

templates/edit_post.html

<!DOCTYPE html>
<html>
  <head>
    <title>Edit Post - My FastAPI Forum</title>
    <style>
      body {
        font-family: sans-serif;
        margin: 2em;
      }
      form {
        width: 500px;
        margin: 0 auto;
      }
      input,
      textarea {
        width: 100%;
        padding: 8px;
        margin-bottom: 10px;
        box-sizing: border-box;
      }
      button {
        padding: 10px 15px;
        background-color: #007bff;
        color: white;
        border: none;
        cursor: pointer;
      }
      a {
        display: block;
        margin-top: 1em;
        text-align: center;
      }
    </style>
  </head>
  <body>
    <h1>Edit Post</h1>
    <form method="post">
      <input type="text" name="title" value="{{ post.title }}" required /><br />
      <textarea name="content" rows="10" required>{{ post.content }}</textarea
      ><br />
      <button type="submit">Update Post</button>
    </form>
    <a href="/posts">Cancel</a>
  </body>
</html>

The core of this template is a form with two input fields: title and content. We use Jinja2's {{ post.title }} and {{ post.content }} syntax to pre-populate the form with the post data passed from the backend.

Step 2: Add API Routes for Editing

Next, we need to add two new routes in main.py to handle the editing logic. Open the main.py file and add the following code:

main.py (Adding new routes)

# ... (Previous imports and app, templates definitions remain unchanged) ...

# --- Routes ---

# ... (Previous routes like /, /posts, /api/posts remain unchanged) ...

@app.get("/posts/{post_id}/edit", response_class=HTMLResponse)
async def get_edit_post_form(
    request: Request,
    post_id: int,
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    if not current_user:
        return RedirectResponse(url="/login", status_code=status.HTTP_302_FOUND)

    result = await db.execute(select(models.Post).where(models.Post.id == post_id))
    post = result.scalar_one_or_none()

    if not post:
        raise HTTPException(status_code=404, detail="Post not found")

    if post.owner_id != current_user.id:
        raise HTTPException(status_code=403, detail="Not authorized to edit this post")

    return templates.TemplateResponse("edit_post.html", {"request": request, "post": post})


@app.post("/posts/{post_id}/edit")
async def edit_post(
    post_id: int,
    title: str = Form(...),
    content: str = Form(...),
    db: AsyncSession = Depends(get_db),
    current_user: Optional[models.User] = Depends(get_current_user)
):
    if not current_user:
        return RedirectResponse(url="/login", status_code=status.HTTP_302_FOUND)

    result = await db.execute(select(models.Post).where(models.Post.id == post_id))
    post = result.scalar_one_or_none()

    if not post:
        raise HTTPException(status_code=404, detail="Post not found")

    if post.owner_id != current_user.id:
        raise HTTPException(status_code=403, detail="Not authorized to edit this post")

    post.title = title
    post.content = content
    await db.commit()

    return RedirectResponse(url="/posts", status_code=status.HTTP_303_SEE_OTHER)

# ... (Subsequent routes like /register, /login, /logout remain unchanged) ...

Here, we've added two routes:

GET /posts/{post_id}/edit: This route finds a post in the database based on the post_id from the URL. It then verifies that the post.owner_id matches the current_user.id. If the validation passes, it renders the edit_post.html template, passing the queried post object to it.
POST /posts/{post_id}/edit: This route receives the new title and content from the form and updates the attributes of the post object. This operation also validates the login status and post ownership.

Step 3: Add an Entry Point on the Main Page

The routes are ready. Next, we need to add an entry point for posts so that users can access the edit page.

Modify the templates/posts.html file.

templates/posts.html (Updated)

... (File header and stylesheet remain unchanged) ...
<body>
    ... (Header and new post form sections remain unchanged) ...

    <hr />
    <h2>Post List</h2>

    {% for post in posts %}
    <div style="border: 1px solid #ccc; padding: 10px; margin-bottom: 10px;">
      <h3>{{ post.title }}</h3>
      <p>{{ post.content }}</p>
      <small>Author: {{ post.owner.username if post.owner else 'Unknown' }}</small>

      {% if current_user and post.owner_id == current_user.id %}
      <div style="margin-top: 10px;">
        <a href="/posts/{{ post.id }}/edit">Edit</a>
      </div>
      {% endif %}
    </div>
    {% endfor %}
</body>
</html>

We've added a Jinja2 conditional statement below the post information:
{% if current_user and post.owner_id == current_user.id %}

If the current user is logged in (current_user exists) and the owner_id of the post matches the id of the current user, an "Edit" link pointing to /posts/{{ post.id }}/edit will be displayed.

This way, users will only see the edit button on their own posts and cannot edit posts belonging to others.

Run and Verify

Restart your uvicorn server:

uvicorn main:app --reload

Visit http://127.0.0.1:8000 and log in.

Find a post you previously published, and you will see an "Edit" link below it. For posts by other users, you will not see the "Edit" link.

Click "Edit," and the page will redirect to the edit form, pre-filled with the post's original title and content.

Modify the content and click "Update Post." The page will redirect back to the homepage, where you will see that the post content has been successfully updated.

Deploying the Project Online

Just like in the first tutorial, you can deploy the results of this step online to let your friends experience the changes and progress of your project.

A simple deployment solution is to use Leapcell.

If you have deployed before, simply push the code to your Git repository, and Leapcell will automatically redeploy the latest code for you.

If you haven't used Leapcell's deployment service before, you can refer to the tutorial in this article.

Summary

Now that the forum has an editing feature, it has become more complete.

Besides posting, interaction is essential for a forum. When users see an interesting (or controversial) post, they will want to share their opinions below it.

In the next article, we will add an interactive feature to the forum: implementing comments and replies for posts, allowing users to have discussions around them.

Read on our blog

Related Posts:

Forem: Leapcell

Build a Docusaurus-like Site with FastAPI: Step 6 - Sidebar Generation

Step 1: Create Sidebar Layout Styles

Step 2: Modify the HTML Template

Step 3: Implement Directory Scanning Logic

Step 4: Add a Second Document for Testing

Step 5: Run and Test

Summary

Other

Build a Docusaurus-like Site with FastAPI: Step 5 - Handling Static Files

Why Won't the Image Display?

Step 2: Create a Convention for Document Resources

Step 3: Mount the Document Resource Directory in FastAPI

Step 4: Update the Image Link in Markdown

Step 5: Run and Test

Summary

Other

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

Step 1: Install the Frontmatter Parsing Library

Step 2: Add Frontmatter to Our Markdown Document

Step 3: Modify main.py to Parse Frontmatter

Step 4: Run and Test

Conclusion and Next Steps

Other

Build a Docusaurus-like Site with FastAPI: Step 3 - Code Highlighting

Step 1: Install Highlighting Dependencies

Step 2: Configure Static Files Directory and CSS

Step 3: Generate the Highlighting CSS File

Step 4: Mount the Static Directory in FastAPI

Step 5: Include the CSS in the HTML Template

Step 6: Enable Markdown Extensions

Step 7: Run and Test

Deploying the Project Online

Conclusion and Next Steps

Build a Docusaurus-like Site with FastAPI: Step 2 - Render Markdown

Step 1: Install a Markdown Parsing Library

Step 2: Create Our First Markdown Document

Step 3: Create a Template for Rendering Documents

Step 4: Create the Markdown Rendering Route

Step 5: Run and Test

Deploying the Project Online

Summary and Next Steps

Build a Docusaurus-like Site with FastAPI: Step 1 - HTML Template

Step 1: Environment Setup and Dependency Installation

Step 2: Set Up the Project Skeleton

Step 3: Write Your First FastAPI App (JSON Version)

Step 4: Configure the Jinja2 Template Engine

Step 5: Create Our First HTML Template

Step 6: Render the Template with TemplateResponse

Deploying the Project Online

Summary

Build Your Own Forum with FastAPI: Step 10 - Categories

Step 1: Update Database Models

Step 2: Update Database Table Structure

Create the categories table

Create default categories

Modify the posts table

Handle existing posts

Set to Not Null

Step 3: Update Post Creation Logic

Step 4: Implement Browsing by Category

Step 5: Update Frontend Templates

Run and Verify

Conclusion

Build Your Own Forum with FastAPI: Step 9 - Upload Images

Step 1: Prepare an S3 Storage Bucket

Step 2: Install Dependencies

Step 3: Add Configuration

Step 4: Create S3 Upload Utility

Step 5: Update Database Model

Step 6: Refactor the Backend Route

Step 7: Update Frontend Templates

Run and Verify

Conclusion

Build Your Own Forum with FastAPI: Step 8 - Full Text Search

Step 1: Database Search Infrastructure (SQL)

Add the tsvector Column

Use a Trigger to Automatically Update the tsvector Column

Create the Search Index

Step 2: Backfill Existing Data

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

Create the `categories` table

Modify the `posts` table