Static Site Generator

A lightweight static site generator built from scratch in Python that transforms Markdown files into beautiful, responsive HTML websites.

---

Architecture

The flow of data through the full system is:

• Markdown files are in the /content directory. A template.html file is in the root of the project.
• The static site generator (the Python code in src/) reads the Markdown files and the template file.
• The generator converts the Markdown files to a final HTML file for each page and writes them to the /docs directory.
• Start the built-in Python HTTP server (a separate program, unrelated to the generator) to serve the contents of the /docs directory on http://localhost:8888 (local machine).
• Open a browser and navigate to http://localhost:8888 to view the rendered site.
  
  

How the SSG Works

• Delete everything in the /docs directory.
• Copy any static assets (HTML template, images, CSS, etc.) to the /docs directory.
• Generate an HTML file for each Markdown file in the /content directory. For each Markdown file:
  • Open the file and read its contents.
  • Split the markdown into "blocks" (e.g. paragraphs, headings, lists, etc.).
  • Convert each block into a tree of HTMLNode objects. For inline elements (like bold text, links, etc.) we will convert:
    • Raw markdown -> TextNode -> HTMLNode
  • Join all the HTMLNode blocks under one large parent HTMLNode for the pages.
  • Use a recursive to_html() method to convert the HTMLNode and all its nested nodes to a giant HTML string and inject it in the HTML template.
• Write the full HTML string to a file for that page in the /docs directory.

Build Scripts

main.sh — local development

Purpose: fast rebuilds for local preview

Command: python3 src/main.py (uses root / so links work locally)

When to use: while editing content/templates then serve docs/ locally

build.sh — production (GitHub Pages)

Purpose: generate the site exactly as it will appear at https://USERNAME.github.io/REPO_NAME/

Command: python3 src/main.py "/REPO_NAME/" (prefixes links with the repo base path)

When to use: before commit/push to deploy via GitHub Pages