Building a Blog Platform with Docker #3: Markdown Rendering

Quick one-liner: Stop writing HTML for your posts. Parse .md files with YAML frontmatter and render them in Flask.

---

Why This Matters

Last time you built a blog that looks like a blog. Teal nav, dark background, editorial post list. Nice.

But the post in that list? It's hardcoded HTML. Every time you want a new post, you have to edit a template. That's not a blog platform, that's a website.

A real blog platform lets you write a file, drop it in a folder, and have it appear. That's what Markdown gives you.

Why Markdown?

• You write in plain text: no <p> tags, no &, no forgetting to close a <div>
• It's readable as-is, even before rendering
• Every major writing tool supports it
• Easy to version control in git

By the end of this post, you'll be able to drop a .md file into a folder and have Flask render it as a proper HTML page.

---

Starting Point

You should have this from last time:

tiohub-blog/
├── app.py
├── static/
│   └── js/
│       └── tailwind.config.js
└── templates/
    └── index.html

If you don't have this, go back to Episode 2 first.

---

Step 1: Install the Packages

You need two libraries:

• Markdown: converts Markdown syntax to HTML
• PyYAML: parses the YAML frontmatter at the top of each post

Make sure your venv is active first:

$ source venv/bin/activate

Install both:

$ pip install Markdown PyYAML

Save them to requirements.txt:

$ pip freeze > requirements.txt

Why pip freeze? It saves every installed package with its exact version. Anyone cloning your repo can run pip install -r requirements.txt and get the exact same environment. We'll need this when we add Docker later.

---

Step 2: Create Your First Post

Create the content folder:

$ mkdir -p content/posts

Create content/posts/hey-markdown.md:

---
title: "Hey Markdown"
date: 2026-04-25
tags: [meta, blog]
---

This is my first post written in Markdown.

No more HTML by hand. No more forgetting to close a `<div>`. Just write, save, done.

Here's what Markdown looks like in practice:

- **Bold** with double asterisks
- *Italic* with single asterisks
- `Code` with backticks

And a code block:

\```

bash
$ source venv/bin/activate
# apt update
\

```

python
print("First Markdown post, and it actually works")
\

That's it. Clean to write, clean to read.

The section between the --- markers at the top is called frontmatter. It's YAML, a simple key-value format. The title, date, and tags fields are metadata about the post. The Markdown content starts after the second ---.

---

Step 3: Write the Parse Function

Open app.py. Add the imports at the top:

import yaml
import markdown

Now add a parse_post() function below the imports:

def parse_post(filepath):
    with open(filepath, 'r') as f:
        content = f.read()

    if content.startswith('---'):
        parts = content.split('---', 2)
        meta = yaml.safe_load(parts[1])
        body = parts[2].strip()
    else:
        meta = {}
        body = content

    meta['content'] = markdown.markdown(
        body,
        extensions=['fenced_code', 'tables']
    )
    return meta

What this does:

1. Reads the .md file
2. Checks if it starts with --- (frontmatter present)
3. Splits on --- to separate the YAML from the Markdown
4. Parses the YAML into a Python dict (meta)
5. Converts the Markdown body to HTML and stores it as meta['content']
6. Returns the whole thing: metadata and rendered HTML together

Why fenced_code and tables? The base markdown library is minimal. The fenced_code extension enables code blocks with triple backticks. The tables extension adds table support. Both are included with the library, no extra install needed.

---

Step 4: Add a Route

Add a new route to app.py:

@app.route('/2026/04/hey-markdown')
def hey_markdown_post():
    post = parse_post('content/posts/hey-markdown.md')
    return render_template('post.html', post=post)

Why this URL format? This matches Blogger's URL pattern: /<year>/<month>/<slug>. My current blog is on Blogger, and I'm planning to migrate it to this platform. If the URLs match from the start, existing posts won't need 301 redirects when I move them over.

In Episode 4, this becomes a dynamic route, /<int:year>/<int:month>/<slug>, that looks up any post by its date and slug. For now, we're hardcoding it to prove the parsing works.

Your full app.py should now look like this:

import yaml
import markdown
from flask import Flask, render_template

app = Flask(__name__)

def parse_post(filepath):
    with open(filepath, 'r') as f:
        content = f.read()

    if content.startswith('---'):
        parts = content.split('---', 2)
        meta = yaml.safe_load(parts[1])
        body = parts[2].strip()
    else:
        meta = {}
        body = content

    meta['content'] = markdown.markdown(
        body,
        extensions=['fenced_code', 'tables']
    )
    return meta

@app.route('/')
def index():
    return render_template('index.html')

@app.route('/2026/04/hey-markdown')
def hey_markdown_post():
    post = parse_post('content/posts/hey-markdown.md')
    return render_template('post.html', post=post)

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8000, debug=True)

---

Step 5: Create the Post Template

Create templates/post.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>{{ post.title }}</title>
    <link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=DM+Sans:wght@400;500;700&display=swap" rel="stylesheet">
    <script src="https://cdn.tailwindcss.com?plugins=typography"></script>
    <script src="{{ url_for('static', filename='js/tailwind.config.js') }}"></script>
</head>
<body class="bg-slate-950 text-gray-100 font-sans min-h-screen flex flex-col">

    <!-- Navbar -->
    <nav class="bg-brand-700 border-b border-brand-600">
        <div class="max-w-6xl mx-auto px-6 py-4 flex items-center justify-between">
            <a href="{{ url_for('index') }}" class="font-serif text-xl text-white">
                David Tio's Blog
            </a>
            <div class="flex items-center space-x-6">
                <a href="/" class="text-teal-100 hover:text-white font-medium text-sm transition duration-200">Home</a>
                <a href="#" class="text-teal-100 hover:text-white font-medium text-sm transition duration-200">Series</a>
                <a href="#" class="text-teal-100 hover:text-white font-medium text-sm transition duration-200">About</a>
            </div>
        </div>
    </nav>

    <!-- Post -->
    <main class="max-w-3xl mx-auto px-6 py-16 flex-1 w-full">

        <p class="text-gray-500 text-sm mb-4">{{ post.date }}</p>
        <h1 class="font-serif text-4xl text-white leading-tight mb-8">{{ post.title }}</h1>

        <div class="border-t border-slate-800 mb-10"></div>

        <div class="prose prose-invert max-w-none
                    prose-headings:font-serif prose-headings:text-white
                    prose-p:text-gray-300 prose-p:leading-relaxed
                    prose-a:text-brand-500 prose-a:no-underline hover:prose-a:underline
                    prose-code:text-brand-500 prose-code:bg-slate-800 prose-code:px-1 prose-code:rounded
                    prose-pre:p-0 prose-pre:bg-transparent prose-pre:border-0
                    prose-strong:text-white
                    prose-li:text-gray-300">
            {{ post.content | safe }}
        </div>

    </main>

    <!-- Footer -->
    <footer class="bg-brand-700 border-t border-brand-600">
        <div class="max-w-6xl mx-auto px-6 py-6 flex items-center justify-between">
            <p class="text-teal-100 text-sm">&copy; 2026 David Tio.</p>
            <div class="flex space-x-6">
                <a href="#" class="text-teal-100 hover:text-white text-sm transition-colors duration-200">LinkedIn</a>
                <a href="#" class="text-teal-100 hover:text-white text-sm transition-colors duration-200">Twitter</a>
                <a href="#" class="text-teal-100 hover:text-white text-sm transition-colors duration-200">GitHub</a>
            </div>
        </div>
    </footer>

</body>
</html>

A few things to note:

{{ post.content | safe }}: The | safe filter tells Flask's template engine not to escape the HTML. Without it, you'd see raw <p> and <h2> tags on the page instead of rendered HTML. This is safe here because you control the content, it's your own Markdown files, not user input.

prose classes: These are Tailwind Typography utility classes that style HTML content you don't control directly. Without them, the rendered Markdown (<h1>, <p>, <ul>, etc.) would inherit no styles at all from Tailwind, because Tailwind resets all browser defaults by design. The prose classes restore readable typography for body content.

prose-pre:p-0 prose-pre:bg-transparent prose-pre:border-0: These override the default <pre> styling that prose applies. In the next step we'll add a JavaScript file that wraps each code block in a styled container with a language label and a Copy button. Those wrapper elements provide the background, padding, and border, so we strip the defaults here to avoid double-styling. If you're not planning to add the code-block wrapper yet, you can swap these for prose-pre:bg-slate-800 prose-pre:border prose-pre:border-slate-700 for now.

Wait, do I need to install anything for prose? No package install is needed for this tutorial because the Tailwind Play CDN can enable first-party plugins through the script URL. The ?plugins=typography part is what makes the prose classes available.

---

Step 6: Format the Date

Right now, {{ post.date }} outputs exactly what's in your YAML: 2026-04-25.

I generally use YYYY-MM-DD in my coding files. It's great for sorting and it keeps everything in chronological order. But it doesn't read like a blog post date. Let's format it into something easier for readers.

Open app.py. Add the datetime import at the top:

from datetime import datetime

Now add a format_date() function below parse_post():

def format_date(date_value):
    """Convert YYYY-MM-DD to '01 January 2026' format."""
    if isinstance(date_value, str):
        date_value = datetime.strptime(date_value, '%Y-%m-%d').date()
    return date_value.strftime('%d %B %Y')

What this does:

• Accepts either a string ("2026-04-25") or a date object (PyYAML sometimes parses dates automatically)
• Converts string input to a proper date object
• Returns it formatted as 25 April 2026

Now update app.py to apply the formatting when returning the post:

@app.route('/2026/04/hey-markdown')
def hey_markdown_post():
    post = parse_post('content/posts/hey-markdown.md')
    post['date'] = format_date(post.get('date', ''))
    return render_template('post.html', post=post)

The date in your template will now read 25 April 2026 instead of 2026-04-25.

---

Step 7: Better Code Blocks

At this point the page works. Markdown renders, the layout matches the rest of the site. But the code blocks are plain, just a dark box with no label and no way to copy the content.

Since we're building a platform for technical content, this matters. Readers want to copy commands and snippets without selecting text manually.

We'll fix this with a small JavaScript file. Create it in static/js/.

Create static/js/code-blocks.js:

document.querySelectorAll('pre').forEach(function(pre) {
    var code = pre.querySelector('code');
    var lang = '';
    if (code && code.className) {
        var match = code.className.match(/language-([\w-]+)/);
        if (match) lang = match[1];
    }

    function copyText() {
        var text = code.innerText;
        var shellLanguages = ['bash', 'sh', 'shell', 'zsh', 'console'];

        if (shellLanguages.indexOf(lang) !== -1) {
            return text
                .split('\n')
                .map(function(line) {
                    return line.replace(/^\s*[$#]\s+/, '');
                })
                .join('\n')
                .trimEnd();
        }

        return text;
    }

    var wrapper = document.createElement('div');
    wrapper.className = 'rounded-lg border border-slate-700 overflow-hidden my-6';

    var header = document.createElement('div');
    header.className = 'flex items-center justify-between bg-slate-800 px-4 py-2 border-b border-slate-700';

    var label = document.createElement('span');
    label.className = 'text-xs text-gray-400 font-mono';
    label.innerText = lang || 'code';

    var btn = document.createElement('button');
    btn.innerText = 'Copy';
    btn.className = 'text-xs text-gray-400 hover:text-white bg-slate-700 hover:bg-slate-600 px-2 py-1 rounded transition-colors duration-200';

    btn.addEventListener('click', function() {
        navigator.clipboard.writeText(copyText()).then(function() {
            btn.innerText = 'Copied!';
            setTimeout(function() { btn.innerText = 'Copy'; }, 2000);
        });
    });

    header.appendChild(label);
    header.appendChild(btn);

    pre.className = 'bg-slate-900 p-4 overflow-x-auto m-0 text-sm';

    pre.parentNode.insertBefore(wrapper, pre);
    wrapper.appendChild(header);
    wrapper.appendChild(pre);
});

What this does:

• Finds every <pre> block on the page after it loads
• Reads the language from the class="language-python" attribute added by the fenced_code extension
• Wraps the block in a styled container with a header bar showing the language label and a Copy button
• Uses navigator.clipboard.writeText() to copy the code text
• Strips leading $ and # prompts from shell snippets before copying, so readers can paste commands directly
• Changes the button to "Copied!" for 2 seconds as feedback

Now update post.html with two changes. First, override the prose-pre defaults so they don't conflict with the custom wrapper the script builds:

prose-pre:p-0 prose-pre:bg-transparent prose-pre:border-0

Second, add the script tag just before </body>:

    <script src="{{ url_for('static', filename='js/code-blocks.js') }}"></script>

</body>

The script tag goes at the bottom, after the page content has loaded, so that querySelectorAll('pre') finds the rendered blocks.

Your prose-pre classes from Step 5 already have this covered, so you don't need to change anything in the <div class="prose ..."> block.

---

Step 8: Test It

Run the app:

$ python app.py

Visit http://localhost:8000/2026/04/hey-markdown.

It should look like this:

Try the Copy button on the bash block. It should leave out the $ and # prompts, so the copied text is ready to paste into your terminal.

The homepage at http://localhost:8000 still shows the hardcoded post list from Episode 2. That's fine for now, we'll wire everything together in Episode 4.

---

What You've Built

Your file structure is now:

tiohub-blog/
├── app.py
├── requirements.txt
├── static/
│   └── js/
│       ├── tailwind.config.js
│       └── code-blocks.js
├── templates/
│   ├── index.html
│   └── post.html
└── content/
    └── posts/
        └── hey-markdown.md

You've added:
✅ Markdown and PyYAML installed and saved to requirements.txt
✅ parse_post(): reads a .md file, splits frontmatter from content, returns both
✅ format_date(): converts 2026-04-25 to 25 April 2026 for display
✅ /<year>/<month>/<slug> URL format matching Blogger's pattern
✅ post.html template with matching nav, footer, and Tailwind Typography styles
✅ Code blocks styled as boxes with a language label and one-click copy button

---

Coming Up

Next time: multiple posts. We'll scan the content/posts/ folder for all .md files, sort them by date, and list them on the homepage. We'll also make the route dynamic, /<int:year>/<int:month>/<slug>, so any post can be reached by its date and filename.

The hardcoded post in index.html goes away. The hardcoded route in app.py goes away too.

---

Found this helpful? Share it with your network or drop a comment below.

---

SEO Metadata

• Title: Building a Blog Platform with Docker #3: Markdown Rendering (2026)
• Meta Description: Stop writing HTML for every blog post. Parse Markdown files with YAML frontmatter in Flask using the Markdown and PyYAML libraries.
• Target Keywords: flask markdown rendering, pyyaml frontmatter flask, python markdown blog, flask blog markdown tutorial 2026
• Word Count: ~1,100