systheme

README

fuego-systheme

The system theme for the Fuego meta-engine: point it at a repository and it renders the engineering artifacts the repo already contains as one navigable site that reads like the repo itself. Nothing is written into the repository.

• a repo-structure sidebar on every page — the file tree, artifacts as links, current file highlighted;
• a landing page that orients: the root modules and what each contains, the decisions currently in force (superseded history one click away at /decisions/), the rendered README, and the .gitignore in a collapsible;
• the OpenAPI index shaped like the yaml devs already scan — info, servers, tags, paths with method-colored links, components.schemas;
• the DBML schema as an ERD — a mermaid entity-relationship diagram generated from the tables, keys, and refs, above the linked table pages.

Demo: demo-fuego-systheme — a fictional AI service rendered at gofuego.github.io/demo-fuego-systheme.

What it renders

Every fuego-formats parser, plus the engine's markdown parser:

Artifact	Claimed as	Becomes
OpenAPI 3 specs	*.openapi.yaml, openapi.yaml, swagger.json, …	an API section: index, a page per tag, operation, and schema
DBML schemas	*.dbml	a schema index plus a page per table (columns, indexes, linked refs)
Playwright suites	*.spec.ts, *.test.ts, .js variants	a page per spec, suite, and test, with tags and annotations
Dockerfiles	Dockerfile, Dockerfile.*, *.dockerfile	a page per build under /dockerfiles/, stage by stage
Kubernetes manifests	*.k8s.yaml, *.k8s.yml, *.k8s	a page per resource, plus the /by-kind/ taxonomy
ADRs	*.adr.md	a page per decision under /decisions/, with status and supersession
Mermaid diagrams	*.mmd	a page per diagram (rendered client-side)
Markdown docs	*.md	prose pages; repo-relative links to other artifacts are rewritten to their rendered pages

The dashboard at / counts and links every family; tags from ADR frontmatter, OpenAPI operations, and Playwright suites share one /tags/ taxonomy.

Use the CLI

go run github.com/gofuego/fuego-systheme/cmd/fuego-systheme@latest \
  -site-name "My System" /path/to/repo serve

# CI / deploy:
go run github.com/gofuego/fuego-systheme/cmd/fuego-systheme@latest \
  -site-name "My System" -base-url /my-repo -strict-links -output build . build

Commands: build, serve, validate. Flags: -site-name, -base-url, -output, -strict-links.

Use as a pack

import systheme "github.com/gofuego/fuego-systheme"

eng := engine.New()
eng.Use(systheme.Pack())

The pack carries the parsers, the theme, the hooks, and config defaults (routes, the tags/resource_kind taxonomies, and an ignore list of non-artifact trees — .git, node_modules, build, …). Your site's own config and theme/ files override anything the pack supplies; a file in your theme/renderers/ or theme/layouts/ wins over the pack's.

To re-claim differently named files, register a parser yourself before the pack — user-registered parsers take precedence:

eng.Register(kubernetes.Parser(formatkit.WithPatterns("*.yaml")))
eng.Use(systheme.Pack())

Contributing

Contributions require signing the Contributor License Agreement — the CLA-assistant bot will prompt you on your first pull request. Work on develop (the default branch); main is protected and updated by PR.

License

Apache-2.0. See LICENSE and NOTICE.

Documentation

Overview

Package systheme is the Fuego system theme: it renders the engineering artifacts a repository already contains — OpenAPI specs, DBML schemas, Playwright suites, Dockerfiles, Kubernetes manifests, ADRs, Mermaid diagrams, and Markdown docs — as one navigable system site. Register it on any Fuego engine with eng.Use(systheme.Pack()), or point the fuego-systheme CLI at a repository; nothing is written into the repo either way.

Index

• func AggregateArtifacts(pages []*core.Page) ([]*core.Page, error)
• func BuildNavTree(pages []*core.Page) ([]*core.Page, error)
• func BuildOverview(pages []*core.Page) ([]*core.Page, error)
• func ComposeHome(pages []*core.Page) ([]*core.Page, error)
• func EnrichPages(pages []*core.Page) ([]*core.Page, error)
• func Pack() core.Pack
• func ResolveRefLinks(pages []*core.Page) ([]*core.Page, error)
• func RewriteContentLinks(pages []*core.Page) ([]*core.Page, error)
• func Run(repoPath string, opts Options) error
• type Options

Functions

func AggregateArtifacts

func AggregateArtifacts(pages []*core.Page) ([]*core.Page, error)

AggregateArtifacts (a BeforeRender hook) builds the whole-artifact views that no single page's nodes carry — the data lives spread across a tree's child pages, and this hook folds it back onto the root:

• OpenAPI roots gain a "paths" index (every operation, sorted by path, deduplicated across tags) and the info/servers/tags/schemas lists, so the root layout can render the yaml-shaped document devs already know how to scan;
• DBML roots gain an "erd" — mermaid erDiagram source generated from the table pages' columns and refs, rendered client-side.

Everything written is JSON-shaped; BeforeRender mutations never touch the build cache.

func BuildNavTree

func BuildNavTree(pages []*core.Page) ([]*core.Page, error)

BuildNavTree (a BeforeRender hook) assembles the repository file tree the sidebar renders on every page: directories nested as in the repo, one leaf per artifact file linking to its page (tree-expanded children live inside the artifact's own pages, not the file tree). The tree is built once and shared by reference on every envelope — JSON-shaped and read-only from the templates' side.

func BuildOverview

func BuildOverview(pages []*core.Page) ([]*core.Page, error)

BuildOverview (an Index hook) appends the two virtual pages of the process view:

• the landing page at /, composed to orient like landing on the repo: the root modules with what each contains, the decisions currently in force, and (filled in by ComposeHome later) the rendered README and the .gitignore collapsible;
• /decisions/ — the full decision log, every status, for the history the landing page deliberately leaves out.

It runs after ROUTE, so every entry carries the page's real URL.

func ComposeHome

func ComposeHome(pages []*core.Page) ([]*core.Page, error)

ComposeHome (a BeforeRender hook, registered after RewriteContentLinks) finishes the landing page with the repo's own voice: the rendered README (links already rewritten — README sits one level deep, so its page-relative hrefs resolve identically from /) and the .gitignore text for the collapsible. The .gitignore page itself is skipped — it was only ever parsed to end up here.

func EnrichPages

func EnrichPages(pages []*core.Page) ([]*core.Page, error)

EnrichPages (an AfterParse hook) defaults the layout for the parsers that deliberately emit none (markdown, docker, kubernetes, adr — their schema.md contracts leave layout to the consuming pack) and lifts identity out of node attributes into the envelope where taxonomies and listings can see it. All envelope values written here are JSON-shaped, so pages stay cache-eligible.

func Pack

func Pack() core.Pack

Pack returns the systheme format pack: every fuego-formats parser plus the engine's markdown parser (this repo contains no parser code), the system theme, route/taxonomy/ignore defaults, and the hooks that default layouts and build the overview dashboard.

func ResolveRefLinks

func ResolveRefLinks(pages []*core.Page) ([]*core.Page, error)

ResolveRefLinks (a BeforeRender hook) turns the cross-page pointers the parsers emit into browser-resolvable relative hrefs, so renderer templates — which see only the node, never .Site — can link without knowing the base URL:

• tree ref nodes (openapi/dbml/playwright *-ref, dbml-ref) carry a "slug" relative to the tree root; the href climbs out of the current page's slug path first
• taxonomy nodes (page-ref, term-ref) carry a site-absolute "url"

Both gain an "href" attribute relative to the page they render on. It runs BeforeRender deliberately: URLs exist only after ROUTE, and mutations here never reach the build cache (which stores post-PARSE state).

func RewriteContentLinks

func RewriteContentLinks(pages []*core.Page) ([]*core.Page, error)

RewriteContentLinks (a BeforeRender hook) keeps a repository's own relative Markdown links working on the rendered site. Content in a scanned repo is written for the repo view — "see [the schema](../backend/db/schema.dbml)" — so this hook resolves each relative href against the page's source location, and when the target file rendered as a page (including as a tree root), replaces the href with the relative URL of that page. Links to files that aren't pages, absolute URLs, and anchors pass through untouched.

func Run

func Run(repoPath string, opts Options) error

Run builds (or serves) the system site for a repository. Discovery runs over the repo itself — the parsers claim their artifacts by filename — and the pack supplies theme, config, and hooks, so nothing is written into the repository.

Types

type Options

type Options struct {
	SiteName    string // site title (default: "System Docs")
	BaseURL     string // base URL for the site (default: "")
	Output      string // output directory (default: "build")
	Command     string // "build", "serve", or "validate" (default: "serve")
	StrictLinks bool   // fail the build on a broken internal link
}

Options configures a fuego-systheme site build.