TriadicFrameworks SSG

A lightweight static site generator that converts every Markdown file under docs/ into a pre-rendered HTML page in site/ — with RTT traceability metadata, canonical URLs, Open Graph tags, auto-generated TOC, breadcrumb navigation, sitemap, and robots.txt.

Quick Start#

# 1. Install dependencies
pip install -r requirements.txt
 
# 2. Full build
python build.py
 
# 3. Preview locally
cd site && python -m http.server 8000
# → http://localhost:8000

Project Layout#

TriadicFrameworks/
├── build.py                    ← SSG entry point
├── config.py                   ← All site settings and RTT schema
├── requirements.txt            ← Python dependencies
│
├── docs/                       ← Markdown source (edit these)
│   ├── index.md                ← Site home page
│   └── <section>/
│       └── <page>.md
│
├── templates/                  ← Jinja2 HTML templates
│   ├── base.html               ← Master layout (meta, RTT, OG, breadcrumbs)
│   ├── page.html               ← Individual doc page (extends base)
│   └── index.html              ← Site landing / page directory (extends base)
│
├── static/                     ← Copied verbatim to site/static/
│   └── style.css
│
└── .github/workflows/
    └── build.yml               ← CI/CD: build on push → GitHub Pages

site/ is the build output directory — never commit it. Add it to .gitignore.

Build Commands#

python build.py                    # Full build into site/
python build.py --clean            # Wipe site/ then build
python build.py --file docs/x.md  # Rebuild one file only
python build.py --watch            # Incremental rebuild on file change
python build.py --drafts           # Include rtt_stability=draft pages
python build.py --verbose          # Debug-level logging

Build Outputs#

Every full build writes the following into site/:

URL Strategy#

Markdown source files map to clean (trailing-slash) URLs:

index.md in any subdirectory collapses to the parent path — it never produces a /foo/index/ URL.

Markdown Front Matter#

Every .md file may open with a YAML front matter block between --- fences. All fields are optional; defaults are applied from config.py when absent.

---
title: "Page Title"
description: "One-sentence summary for SEO and Open Graph."
date: "2026-07-13"           # ISO 8601 — publication date
modified: "2026-07-13"       # ISO 8601 — last-modified date
keywords: "triadic, docs"    # Comma-separated string or YAML list
 
# RTT fields (see RTT Metadata section below)
rtt_stability:     stable
rtt_content_type:  documentation
rtt_audience:      public
rtt_doc_id:        DOC-001
rtt_owner:         core-team
rtt_review_cycle:  quarterly
rtt_last_reviewed: "2026-07-13"
rtt_tags:          [triadic, concepts, architecture]
---

Use [TOC] anywhere in the body to inline the auto-generated table of contents. The sidebar in base.html also receives the TOC independently.

RTT Metadata#

Every rendered page embeds Round-Trip Traceability fields as <meta> tags. These signal content stability, ownership, and review status to QA tooling, LLM pipelines, and search indexers.

Site-wide defaults (config.py → RTT_DEFAULTS)#

Per-page overrides (front matter key → rendered <meta name>)#

Draft filter#

Pages with rtt_stability: draft are excluded from production builds by default. Run python build.py --drafts to include them (e.g. for staging or preview deployments).

Example rendered output#

<meta name="rtt:schema-version"  content="1.0" />
<meta name="rtt:source-repo"     content="https://github.com/umaywant2/TriadicFrameworks" />
<meta name="rtt:stability"       content="stable" />
<meta name="rtt:doc-id"          content="DOC-001" />
<meta name="rtt:last-reviewed"   content="2026-07-13" />
<meta name="rtt:tags"            content="triadic, concepts, architecture" />
<meta name="source:file"         content="docs/concepts/triadic-model.md" />
<meta name="build:timestamp"     content="2026-07-13T20:14:00Z" />
<meta name="build:generator"     content="TriadicFrameworks SSG v1.0" />

Configuration#

All settings live in config.py. String values can be overridden via environment variables — useful in CI/CD without modifying the file.

Path settings (DOCS_DIR, SITE_DIR, TEMPLATE_DIR, STATIC_DIR) are always resolved relative to config.py and cannot be overridden via env vars — this keeps builds portable across machines and containers.

Excluded files#

The following filenames are skipped by the build regardless of location (comparison is case-insensitive):

readme.md · license.md · contributing.md · changelog.md · authors.md · code_of_conduct.md · _template.md · _draft.md

Markdown Extensions#

Eight extensions are loaded for every page:

CI/CD#

.github/workflows/build.yml triggers on every push to main that touches docs/, templates/, static/, build.py, or config.py.

push → pip install → python build.py --clean → upload site/ → deploy Pages

Setup (one time):

1. Go to Settings → Pages → Source and select GitHub Actions
2. Optionally set repository variables BASE_URL, SITE_NAME, OG_IMAGE under Settings → Secrets and variables → Actions → Variables

The workflow uses OIDC-based id-token permissions — no PAT or deploy key required.

Dependencies#

Install: pip install -r requirements.txt

Local Preview Tips#

# Serve site/ with correct MIME types
cd site && python -m http.server 8000
 
# Build drafts for a staging preview
BASE_URL=http://localhost:8000 python build.py --clean --drafts
 
# Rebuild a single page quickly during authoring
python build.py --file docs/concepts/triadic-model.md
 
# Live authoring loop (requires watchdog)
python build.py --watch --drafts