This is a simple, fast, and customizable static blog generator written in Python. It reads Markdown posts with optional metadata, converts them into static HTML pages using Jinja2 templates, and deploys the site to GitHub Pages automatically via GitHub Actions.

👉 sajjadtalks.github.io/blog

📦 your-blog-repo/ ├─ .github/workflows/build-site.yml # GitHub Actions workflow ├─ README.md # This file ├─ blog/ # Your markdown posts │ ├─ Hello-World.md │ └─ Python-Markdown.md ├─ generate.py # Blog generator script ├─ requirements.txt # Python dependencies ├─ static/ # Static assets (JS, CSS) │ ├─ script.js │ └─ style.css ├─ templates/ # HTML templates │ ├─ base.html │ ├─ index.html │ └─ post.html └─ docs/ # Output folder (auto-generated) 

git clone https://github.com/sajjadtalks/blog.git cd blog

Put your Markdown files inside the blog/ folder. Example:

--- title: Hello World date: 2024-01-01 11:20:00 summary: This is my first post! --- # Welcome to My Blog This is the content of my first blog post.

Each post supports YAML frontmatter with fields like title, date, and summary.

Use Python 3.11+ and run:

pip install -r requirements.txt

python generate.py

The generated HTML site will be saved in the docs/ folder.

You can serve the site locally to preview it:

cd docs python -m http.server

Open http://localhost:8000 in your browser.

This project uses a GitHub Actions workflow to automatically build and deploy your blog to the gh-pages branch whenever you:

• Push to the main branch
• Modify any file in blog/, templates/, static/, generate.py, requirements.txt, or the workflow file itself

1. On Push: The GitHub Action runs generate.py to build the site into docs/
2. Deploy: Uses peaceiris/actions-gh-pages to push the built site to gh-pages
3. GitHub Pages: Serves your static site from the gh-pages branch

Make sure to:

1. Go to your repo’s Settings → Pages
2. Set:
   • Source: gh-pages branch
   • Folder: / (root)

• 🗂 Supports pagination (10 posts per page)
• 📅 Sorts posts by date (newest first)
• 🧠 Builds a search_index.json file for custom search
• 🎨 Styled with custom style.css and supports codehilite
• ✅ Automatically creates .nojekyll for proper GitHub Pages support
• 📄 Supports Markdown extensions like tables, task lists, code blocks

• Python 3.11+
• See requirements.txt for packages like:
  • markdown
  • jinja2
  • python-frontmatter
  • pymdown-extensions

--- title: My First Blog Post date: 2025-04-15 11:20:00 summary: This post talks about Python static site generators. --- # Hello Static Blogging! Here is **some content** with `code`. ``` python print("Hello World")``` 

You do not need to manually push to gh-pages. Just push your Markdown or template changes to main, and the deployment is automatic 🚀

MIT License — Free to use and modify.

Created with ❤️ by @sajjadtalks