Quick and dirty python SSG that lets you bodge things the way HTML+CSS+JS is good at
Files
README.md

Syzygy SSG #

A simple SSG for easy and extensible website creation. Most SSGs feel the need to bundle a web server, or a theme installer, or anything other than the core functionality of site generation, and I really only want to slap html content into a template and call it a day.

Installation #

pip install [packagedir]

Usage #

syzygy [spec.json]

This will build the site in the spec-designated dist folder, which can then be served by any http server.

spec.json #

A spec.json file in the root directory of your site designates where the content directory, site template, static directory, shortcodes python file, and other objects used in site generation are.

Example spec.json:

{
  "template": "template.html",
  "content": "content",
  "static": "static",
  "dist": "dist",
  "shortcodes": "shortcodes.py"
}
Item Purpose
template The template file is the source HTML that content is pasted into, allowing consistent site theming and content.
content The directory containing Markdown files with optional JSON metadata that are parsed to generate the site pages.
static The directory containing static assets like CSS, JS, and images. Its contents are copied into a static folder inside dist.
dist The output directory where the generated HTML pages and static files are placed. Warning: this directory is entirely deleted before each generation!
shortcodes A Python file containing a shortcodes dictionary mapping names to functions. {{name}} in the text is replaced by the result of function(page_properties, spec_instance).

Creating Content #

Pages are written in Markdown with optional JSON frontmatter blocks. The frontmatter properties will be available inside your shortcodes. You can also use {{shortcode_name}} directly in the markdown.

Example markdown file:

---{"title": "My Post", "date": "2024-01-01"}---

# Hello World

This is a post using a shortcode: {{my_shortcode}}.

Writing Shortcodes #

Your shortcodes.py file should define a dictionary named shortcodes mapping shortcode names to their handler functions. Each function receives two arguments: page_properties (a dictionary) and spec_instance (the current Spec object).

Example shortcodes.py:

def my_shortcode(page_properties, spec_instance):
    title = page_properties.get("title", "Untitled")
    return f"<strong>The title is {title}</strong>"

shortcodes = {
    "my_shortcode": my_shortcode
}