Posted on August 03, 2025
Category: Technology
This post summarizes my journey to add a simple blog module to my Flask-based website, Willconia, using Flask-FlatPages. The goal was to create a personal blog without login functionality, integrated with my existing homepage.
Initially, I provided my index.html and app.py files, which served a basic homepage with a placeholder for a blog. The first proposed solution used an in-memory list of posts, but I wanted a more efficient approach using a pre-existing Python module. Flask-FlatPages was recommended, as it allows blog posts to be written as Markdown files in a pages directory, eliminating the need for a database.
The setup involved:
- Installing Flask-FlatPages and dependencies (PyYAML, Markdown).
- Updating app.py to include routes for /blog (list of posts) and /blog/<path> (individual posts).
- Creating templates (blog.html, post.html) and sample posts (first-post.md, flask-post.md).
- Configuring the pages directory to store .md files with YAML front matter.
However, I hit a snag: accessing /blog resulted in a 500 error due to a YAML parsing issue (mapping values are not allowed here). The error stemmed from incorrect YAML syntax in one of the .md files, likely an extra colon or hidden character. After updating app.py with debug logging and fixing the YAML format (ensuring proper title, date, and UTF-8 encoding), the blog worked perfectly.
I learned that the .md file format is critical. Each file must have valid YAML front matter, like this:
```yaml
title: My Post Title date: 2025-08-03
```
Adding a new post is simple: create an .md file in the pages directory with correct YAML, and Flask-FlatPages automatically detects it. This post itself is a test to confirm that any properly formatted Markdown file can serve as blog material.
Key takeaways:
- Use YYYY-MM-DD for dates.
- Avoid extra colons, spaces, or tabs in YAML.
- Save files in UTF-8 encoding.
- Test incrementally to catch errors early.
This experience taught me the power and simplicity of Flask-FlatPages for personal blogging, as well as the importance of precise Markdown formatting. Now, I can easily add posts like this one to share my tech journey!
Disclaimer: This blog post was created with assistance from Grok 3, an AI developed by xAI, under my direct supervision and guidance to ensure accuracy and alignment with my vision for the content.