A simple and efficient static site generator in Python that converts markdown files into a complete website.
FlatPy is a static site generator that transforms your markdown files into a beautiful website. The project reads markdown content from the content/ folder, applies HTML templates, and generates a ready-to-use static website in the docs/ folder.
Key features:
- 📝 Markdown support - full markdown syntax for content
- 🎨 HTML templates - customizable templates for page styling
- 🗂️ Directory structure - automatic navigation creation from folder structure
- 📱 Static resources - copying CSS, images, and other files
- 🔄 Recursive generation - support for nested directories and blogs
- 🌐 GitHub Pages ready - configurable basepath for deployment
├── src/ # Source code of the generator
│ ├── main.py # Main file - site generation
│ ├── nodes/ # Data models
│ │ ├── textnode.py # TextNode and TextType
│ │ ├── htmlnode.py # HTMLNode, LeafNode, ParentNode
│ │ └── blocknode.py # BlockType for block elements
│ ├── parsers/ # Markdown parsers
│ │ ├── converter.py # HTML conversion
│ │ ├── text_parser.py # Inline element parsing
│ │ └── block_parser.py # Block element parsing
│ └── tests/ # Tests
├── content/ # Markdown content of the site
│ ├── index.md # Home page
│ ├── blog/ # Blog
│ └── contact/ # Contact information
├── static/ # Static files
│ ├── index.css # CSS styles
│ └── images/ # Images
├── docs/ # Generated site (output for GitHub Pages)
├── template.html # HTML template for pages
├── main.sh # Local development script
└── build.sh # Production build script
- Bold text:
**text** - Italic:
*text* Code:`code`- Links:
[text](url) - Images:
- Headings:
# H1,## H2,### H3, etc. - Code blocks:
- Quotes:
> quote - Lists:
- itemand1. item - Paragraphs
# Run for local development (default basepath "/")
./main.sh
# Or directly via Python
python3 -m src.main# Build for GitHub Pages deployment
./build.sh
# This runs: python3 -m src.main "/flatpy"# Build with custom basepath
python3 -m src.main "/custom-path/"Place your markdown files in the content/ folder:
content/
├── index.md # Home page
├── about.md # About page
└── blog/ # Blog
├── post1.md # First post
└── post2.md # Second post
Edit template.html to change the design:
<!doctype html>
<html>
<head>
<title>{{ Title }}</title>
<link href="/index.css" rel="stylesheet" />
</head>
<body>
<article>{{ Content }}</article>
</body>
</html>Place CSS, images, and other static files in the static/ folder. They will be copied to docs/ during generation.
This project is configured for easy deployment to GitHub Pages:
-
Build the site:
./build.sh
-
Commit and push:
git add . git commit -m "Deploy site" git push origin main
-
Configure GitHub Pages:
- Go to your repository settings
- Navigate to Pages section
- Set source to "Deploy from a branch"
- Select "main" branch and "/docs" folder
- Save settings
-
Access your site: Your site will be available at:
https://USERNAME.github.io/REPO_NAME/
The build.sh script automatically configures all paths for GitHub Pages deployment, ensuring CSS, images, and internal links work correctly with the /flatpy basepath.
# Code formatting
make format
# Code style checking
make lint
# Run tests
make test
# Full check (formatting + linting + tests)
make check
# Help
make helpfrom src.parsers import markdown_to_html_node, extract_title
# Convert markdown to HTML
markdown_text = """
# Heading
This is **bold** text with *italic*.
- List item 1
- List item 2
"""
html_node = markdown_to_html_node(markdown_text)
html_output = html_node.to_html()
# Extract title
title = extract_title(markdown_text)The project uses modern tools to maintain code quality:
- Black — automatic code formatting
- isort — import sorting
- flake8 — code style checking
- unittest — testing
All tools are configured to work together and are available through convenient Makefile commands.
- Clean architecture: code organized by functionality with clear separation of concerns
- Modularity: easily understandable and modifiable code
- Extensibility: can easily add new markdown elements or output formats
- Well tested: comprehensive test suite covers all functionality
- Code quality: automatic formatting and style checking
- Deployment ready: built-in support for GitHub Pages and other static hosts
After running the generator, a ready-to-use static website will appear in the docs/ folder, which can be deployed on any web server or static site hosting (GitHub Pages, Netlify, Vercel, etc.).