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 — an overview dashboard, a section per artifact, cross-linked and taxonomy-indexed. Nothing is written into the repository.

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 BuildOverview(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 BuildOverview

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

BuildOverview (an Index hook) appends the dashboard: one virtual page at / summarizing every artifact family with counts and entry links. It runs after ROUTE, so entries carry the pages' real URLs.

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.