Building This Blog: From Zero to GitHub Pages

Welcome to Sam's Log Supplemental! This is the story of how this blog came to life - from conception to deployment in under an hour using modern Python tooling.

🎯 The Goal

I wanted a simple, fast blog that could:

• Write posts in Markdown
• Deploy automatically on every push
• Look professional with minimal effort
• Be SEO-friendly out of the box
• Support modern features like dark mode and RSS

🛠️ The Tech Stack

🏗️ Architecture Overview

The blog follows a simple static site generator pattern:

1. Content - Markdown files with YAML frontmatter
2. Templates - Jinja2 HTML templates
3. Build Script - Python script that processes everything
4. Deployment - GitHub Actions automates the pipeline

def build_site():
    # Setup Markdown with extensions
    md = markdown.Markdown(
        extensions=["meta", "fenced_code", "codehilite", "toc", "tables"]
    )

    # Process markdown posts with frontmatter
    posts = []
    for filename in sorted(os.listdir('posts')):
        if filename.endswith('.md'):
            title, date, description, tags, content = extract_metadata(filepath)
            html_content = md.convert(content)
            posts.append({
                'title': title,
                'content': html_content,
                'date': date,
                'description': description,
                'tags': tags,
                'filename': filename.replace('.md', '.html'),
                'url': f"/{filename.replace('.md', '.html')}"
            })

    # Copy assets and static files
    shutil.copytree("assets", "docs/assets")
    shutil.copytree("static", "docs/static")

    # Generate pages, sitemap, RSS feed
    generate_index(posts)
    generate_sitemap(posts)
    generate_rss(posts)

✨ Features Implemented

🚀 Deployment Pipeline

The GitHub Actions workflow includes advanced features:

- name: Setup Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.13'
    cache: 'pip'

- name: Install Poetry
  uses: snok/install-poetry@v1
  with:
    version: latest
    virtualenvs-create: true
    virtualenvs-in-project: true

- name: Load cached venv
  uses: actions/cache@v4
  with:
    path: .venv
    key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}

- name: Validate posts
  run: |
    find posts -name "*.md" -exec poetry run python -c "import frontmatter; frontmatter.load(open('{}'))" \;

- name: Build site
  run: poetry run python buildblog.py

- name: Test deployed site
  run: python test_site.py

Every push to main triggers:

1. Python 3.13 setup with pip caching
2. Poetry installation with virtual environment caching
3. Dependency caching for faster builds
4. Markdown post validation
5. Site building with error handling
6. Build artifact validation
7. Deployment to GitHub Pages
8. Live site testing

💡 Key Decisions

📊 Performance Results

🔮 Future Enhancements

Some ideas for future iterations:

• Search functionality with client-side indexing
• Comment system integration (GitHub Discussions)
• Analytics dashboard with privacy-focused tracking
• Newsletter signup automation
• Additional themes beyond LCARS and Material 3
• Content management improvements
• Performance monitoring integration

🎉 The Result

The entire setup is maintainable, extensible, and follows current best practices. Most importantly, it gets out of the way and lets me focus on writing.

🔗 Resources

• Repository: sam-fakhreddine/thingsBlog
• Live Site: sam-fakhreddine.github.io/thingsBlog
• Poetry: python-poetry.org
• GitHub Pages: pages.github.com
• GitHub Actions: docs.github.com/actions
• Markdown Extensions: python-markdown.github.io

This post was written in Markdown, processed by Python, and deployed automatically. The future is pretty cool. ✨