Static site generators (SSGs) have taken the web development world by storm. They give you the speed of a plain HTML site while letting you write content in Markdown, reuse templates, and automate builds. In this guide we’ll walk you through building a minimalist yet powerful SSG from scratch using Python and the Jinja2 templating engine. By the end you’ll have a reusable command‑line tool that can turn a folder of Markdown files into a fully‑styled website.
What You’ll Need
- Python 3.8+ installed on your machine
- Basic familiarity with the command line
- Markdown files for content (any text editor will do)
- Jinja2 library (`pip install jinja2`)
- Optional: a CSS framework like Tailwind or Bootstrap for styling
Step 1: Set Up Your Project Structure
First, create a clean directory layout. This separation makes it easy to maintain templates, static assets, and source content.
my_ssg/
├── content/ # Your markdown articles
├── templates/ # Jinja2 HTML templates
├── static/ # Images, CSS, JS
├── build/ # Generated site (git‑ignored)
└── ssg.py # The generator script
Run the following commands to scaffold the folders:
mkdir -p my_ssg/{content,templates,static,build}
Place a simple index.html template in templates/ (we’ll flesh it out later) and add a couple of Markdown files in content/ to test.
Step 2: Install Dependencies and Create a Virtual Environment
Isolating your project’s Python packages prevents version clashes. In the project root, execute:
python -m venv .venv
source .venv/bin/activate # macOS/Linux
.venvScriptsactivate # Windows
Then install Jinja2 and a Markdown parser (we’ll use markdown).
pip install jinja2 markdown
Save these to requirements.txt for future reproducibility:
pip freeze > requirements.txt
Step 3: Write the Core Generator Logic
Open ssg.py and start with imports and basic configuration:
import os import pathlib import markdown from jinja2 import Environment, FileSystemLoader BASE_DIR = pathlib.Path(__file__).parent CONTENT_DIR = BASE_DIR / "content" TEMPLATE_DIR = BASE_DIR / "templates" STATIC_DIR = BASE_DIR / "static" BUILD_DIR = BASE_DIR / "build" env = Environment(loader=FileSystemLoader(str(TEMPLATE_DIR)))
Next, create helper functions to read Markdown, render Jinja2, and write output files.
def render_markdown(md_path):
with open(md_path, "r", encoding="utf-8") as f:
text = f.read()
html = markdown.markdown(text, extensions=["fenced_code", "codehilite"])
return html
def render_page(template_name, **context):
template = env.get_template(template_name)
return template.render(**context)
def write_output(relative_path, content):
output_path = BUILD_DIR / relative_path
output_path.parent.mkdir(parents=True, exist_ok=True)
with open(output_path, "w", encoding="utf-8") as f:
f.write(content)
Now loop over every .md file, convert it, and inject it into the base template.
def build_site():
# Copy static assets first
if STATIC_DIR.exists():
for root, _, files in os.walk(STATIC_DIR):
for file in files:
src = pathlib.Path(root) / file
rel = src.relative_to(STATIC_DIR)
dest = BUILD_DIR / rel
dest.parent.mkdir(parents=True, exist_ok=True)
dest.write_bytes(src.read_bytes())
# Process markdown files
for md_file in CONTENT_DIR.rglob("*.md"):
html_body = render_markdown(md_file)
# Derive output filename (e.g., about.md -> about/index.html)
slug = md_file.stem
output_rel = pathlib.Path(slug) / "index.html"
page_html = render_page("base.html", content=html_body, title=slug.title())
write_output(output_rel, page_html)
if __name__ == "__main__":
BUILD_DIR.mkdir(exist_ok=True)
build_site()
print("Site generated in 'build' folder")
This script does three things: copies static files, converts Markdown to HTML, and wraps each piece of content with the base.html template.
Step 4: Create a Base Jinja2 Template
In templates/base.html, add a minimal HTML skeleton. Feel free to plug in a CSS framework later.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ title }} | My Static Site</title>
<link rel="stylesheet" href="/static/style.css">
</head>
<body>
<header>
<h1><a href="/">My Static Site</a></h1>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="/about/">About</a></li>
</ul>
</nav>
</header>
<main>
{{ content|safe }}
</main>
<footer>
<p>© {{ now().year }} My Static Site</p>
</footer>
</body>
</html>
Note the {{ content|safe }} filter – it tells Jinja2 not to escape the HTML we generated from Markdown.
Step 5: Add a Simple Home Page and Navigation
Our generator currently treats every Markdown file as a separate page. Let’s add an index.md that lists all pages.
# Welcome to My Site This site is powered by a custom static site generator written in Python. Below are the available pages:</n
Modify build_site() to detect index.md specially:
def build_site():
# (static copy unchanged)
pages = []
for md_file in CONTENT_DIR.rglob("*.md"):
slug = md_file.stem
html_body = render_markdown(md_file)
output_rel = pathlib.Path(slug) / "index.html"
page_html = render_page("base.html", content=html_body, title=slug.title())
write_output(output_rel, page_html)
pages.append({"title": slug.title(), "url": f"/{slug}/"})
# Build the home page using a dedicated template
home_html = render_page("home.html", pages=pages, title="Home")
write_output("index.html", home_html)
Create templates/home.html that extends the base layout:
{% raw %}{% extends "base.html" %}
{% block content %}
Site Index
-
{% for page in pages %}
- {{ page.title }} {% endfor %}
Now running python ssg.py produces a proper index.html with navigation links.
Step 6: Automate Rebuilding with a Watcher (Optional)
During development you don’t want to manually re‑run the script after every change. Install watchdog and add a tiny watcher script.
pip install watchdog
Create watch.py:
import sys
import time
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler
from pathlib import Path
class RebuildHandler(FileSystemEventHandler):
def __init__(self, script_path):
self.script_path = script_path
def on_any_event(self, event):
if event.is_directory:
return
if event.src_path.endswith(('.md', '.html', '.css', '.py')):
print('Change detected – rebuilding...')
os.system(f'python {self.script_path}')
if __name__ == "__main__":
path = Path('.').resolve()
event_handler = RebuildHandler('ssg.py')
observer = Observer()
observer.schedule(event_handler, str(path), recursive=True)
observer.start()
print('Watching for changes... Press Ctrl+C to stop.')
try:
while True:
time.sleep(1)
except KeyboardInterrupt:
observer.stop()
observer.join()
Run python watch.py and edit your Markdown files; the site will rebuild automatically.
Common Mistakes to Avoid
1. Forgetting to escape user‑generated HTML. If you allow raw HTML inside Markdown, make sure you trust the source or sanitize it; otherwise malicious scripts could slip into the final site.
2. Hard‑coding paths. Use pathlib and relative paths as shown. Absolute paths break when you move the project.
3. Missing the |safe filter. Without it, Jinja2 will escape the HTML produced by the Markdown parser, leaving you with visible tags instead of rendered content.
4. Not cleaning the build folder. Old files linger and cause 404s. Add shutil.rmtree(BUILD_DIR, ignore_errors=True) before recreating the folder if you want a fresh start each run.
5. Overlooking character encoding. Always open files with encoding="utf-8" to avoid Unicode errors on non‑ASCII content.
Tips and Tricks
• Use front‑matter. Store metadata (title, date, tags) at the top of each Markdown file using YAML. Parse it with python-frontmatter and pass the data to your template.
• Integrate a CSS framework. Drop a compiled Tailwind CSS file into static/ and reference it in base.html. It gives you a polished look without writing custom styles.
• Generate RSS/Atom feeds. Loop over your pages, collect dates, and render an XML template. This adds SEO value and lets readers subscribe.
• Deploy to GitHub Pages. Push the build/ folder to the gh-pages branch of a repository. A single git push updates your live site.
• Cache markdown conversion. For large sites, store the HTML output of each file in a temporary cache (e.g., pickle) and only re‑render changed files.
Frequently Asked Questions
Do I need a database?
No. A static site generator works entirely with files. All content lives in Markdown, and any dynamic behavior (search, comments) can be added via third‑party JavaScript services.
Can I use Jinja2 filters I’ve written for other projects?
Absolutely. Register custom filters on the Environment object (e.g., env.filters['slugify'] = my_slugify) and use them inside your templates.
How does this compare to popular SSGs like Hugo or Jekyll?
Our DIY generator is intentionally lightweight. Hugo and Jekyll offer many built‑in features (taxonomies, multilingual support, extensive plugins). If you need those, consider them. However, building your own gives you full control, a deeper understanding of the pipeline, and a minimal dependency footprint.
Conclusion
Creating a static site generator with Python and Jinja2 is an excellent way to blend programming practice with real‑world output. You now have a reusable script that reads Markdown, applies beautiful templates, copies static assets, and can even watch for changes during development. Extend it with front‑matter, RSS feeds, or a CI/CD pipeline, and you’ll have a production‑ready SSG tailored to your workflow. Happy coding, and enjoy the speed and security that static sites bring to the modern web!
Photo by Dima Solomin on Unsplash
