Staticgen

Staticgen is a small Python static site generator. It converts Markdown files from content/ into HTML pages, applies template.html, copies assets from static/, and writes the generated site to docs/.

The project was built as a learning exercise, with a focus on learning GitHub Pages and learning testing in Python.

Features

• Converts Markdown content into HTML pages
• Supports headings, paragraphs, code blocks, block quotes, ordered lists, and unordered lists
• Supports inline bold, italic, code, links, and images
• Copies static assets such as CSS and images into the generated site
• Generates output in docs/ so it can be published with GitHub Pages
• Includes unit tests for the Markdown parsing and HTML generation code

Project Structure

.
├── content/          # Markdown source files for the site
├── docs/             # Generated site output for GitHub Pages
├── src/              # Static site generator source code and tests
├── static/           # CSS, images, and other static assets
├── template.html     # HTML template used for every generated page
├── build.sh          # Build command for GitHub Pages deployment
├── main.sh           # Local helper script
└── test.sh           # Test runner

Requirements

• Python 3
• A Unix-like shell such as Bash or Zsh

No third-party Python packages are required.

How It Works

1. Markdown files are stored in content/.
2. Static assets are stored in static/.
3. src/main.py clears and recreates the docs/ directory.
4. Static assets are copied from static/ to docs/.
5. Markdown files are converted to HTML using template.html.
6. The generated HTML site is written to docs/.

Run Locally

Generate the site:

python3 src/main.py

Serve the generated site:

cd docs
python3 -m http.server 8888

Open the site in a browser:

http://localhost:8888

Build for GitHub Pages

Run:

./build.sh

This generates the site with /staticgen/ as the base path:

python3 src/main.py "/staticgen/"

This is useful when publishing the repository as a GitHub Pages project site. If the repository name changes, update the base path in build.sh.

In GitHub Pages, configure the site to publish from the docs/ folder.

Run Tests

Run the full test suite:

./test.sh

Or run the equivalent Python command directly:

python3 -m unittest discover -s src

Add or Edit Content

Add Markdown files under content/. The directory structure is preserved in the generated docs/ output.

For example:

content/blog/example/index.md

becomes:

docs/blog/example/index.html

Each Markdown page should include one top-level # heading. That heading is used as the HTML page title.

After editing content, regenerate the site:

python3 src/main.py

Notes

• Generated files in docs/ are overwritten each time the site is built.
• Root-relative links and image paths are rewritten using the configured base path during generation.
• The current sample content is a Tolkien-themed static site.

License

No license has been specified for this project.