repotheme

README

fuego-repo

The repo theme for the Fuego meta-engine: point it at any repository and it renders every text file as one navigable site that mirrors the repo's own folder structure. Markdown becomes HTML; every other text file becomes a line-numbered source page (the way GitHub shows a file). Nothing is written into the repository.

It is the generic, zero-config sibling of fuego-systheme: where systheme understands specific engineering artifacts (OpenAPI, DBML, Kubernetes, …) through the fuego-formats parsers, fuego-repo has no fuego-formats dependency and no per-format opinions — just the engine's Markdown parser plus one catch-all source parser. It is the lowest-friction way to see Fuego render something real.

Use the CLI

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

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

Install it onto your PATH instead:

go install github.com/gofuego/fuego-repo/cmd/fuego-repo@latest
fuego-repo -site-name "My Repo" /path/to/repo serve

Usage: fuego-repo [flags] <repo-path> [build|serve|validate] — the command defaults to serve. Flags come before the repo path: -site-name, -base-url, -output, -strict-links.

What it renders

File	Becomes
Markdown (*.md)	a prose page (GFM → HTML); in-repo relative links are rewritten to the target's rendered page
Any other text file (*.go, *.ts, *.yaml, Dockerfile, Makefile, .gitignore, …)	a line-numbered source page
Images, PDFs, and anything unrecognized	copied verbatim as a downloadable asset — so README images render and files stay linkable

• Left navigation mirrors the folder tree, collapsed by default, with the path to the current file expanded.
• A "Show code" toggle (off by default) hides source pages from the nav so you see documentation first; flip it to browse code. Folders that contain no documentation collapse away with it. Code pages are always built and reachable by URL — the toggle only affects the tree.
• The index is the repository's README, rendered as the home page. There is no requirement for one: a repo without a root README.md gets a synthesized landing page listing its top-level entries, so the build never breaks.

Use as a pack

import repotheme "github.com/gofuego/fuego-repo"

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

The pack carries the two parsers, the theme, an ignore list of non-content trees (.git, node_modules, build, …), and the hooks that default layouts, build the optional README home, rewrite in-repo links, and assemble the file-tree sidebar. Your site's own config and theme/ files override anything the pack supplies.

The source parser claims a curated set of text extensions and extensionless names (see sourceGlobs in source.go) — deliberately not *.md (the markdown parser owns those) and not binary formats (they stay assets). Register a parser yourself before the pack to claim differently named files; user-registered parsers take precedence.

Contributing

develop is the default branch; main is protected (PR-only). Run go test ./... -race before merging. The theme's style.css is hand-written — no CSS build step. Dependencies stay permissive (no GPL) — the open-core line.

Documentation

Overview

Package repotheme is the Fuego repo theme: point it at any repository and it renders every text file — Markdown as HTML, everything else as a line-numbered source page — as one navigable site that mirrors the repo's own folder structure. It is the generic, zero-config sibling of fuego-systheme: no fuego-formats dependency, no per-format opinions, just the engine's markdown parser plus one catch-all source parser.

Register it on any Fuego engine with eng.Use(repotheme.Pack()), or point the fuego-repo CLI at a repository; nothing is written into the repo either way.

Index

• Constants
• func BuildNavTree(pages []*core.Page) ([]*core.Page, error)
• func EnrichLayouts(pages []*core.Page) ([]*core.Page, error)
• func HomeFromReadme(pages []*core.Page) ([]*core.Page, error)
• func Pack() core.Pack
• func RewriteContentLinks(pages []*core.Page) ([]*core.Page, error)
• func Run(repoPath string, opts Options) error
• type Options

Constants

const SourceType = "source"

SourceType is the page type for every non-Markdown text file. Markdown keeps the engine markdown parser's own type ("md"); everything the source parser claims is this.

Functions

func BuildNavTree

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

BuildNavTree (a BeforeRender hook, registered last) assembles the repository file tree the sidebar renders on every page: directories nested as in the repo, one leaf per rendered page. Each leaf carries a "cat" of "doc" (Markdown) or "code" (everything else) so the sidebar's show-code toggle can hide code by default. The tree is built once and shared by reference on every envelope — JSON-shaped and read-only from the templates' side.

func EnrichLayouts

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

EnrichLayouts (an AfterParse hook) assigns the layout and a display title to every page, since neither parser sets one: Markdown pages render as prose (layout "doc"), source files as a code page (layout "source"). Titles fall back to the file's base name because a parser cannot see the filename. All envelope values written here are JSON-shaped, so pages stay cache-eligible.

func HomeFromReadme

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

HomeFromReadme (an Index hook, after ROUTE) makes the site's index page the repository's README — but never requires one. If a root README.md rendered as a page, its URL is moved to "/" and it renders through the home layout. If there is no README (or something already owns "/", e.g. a root index.md), a minimal virtual home is synthesized listing the top-level entries, so a README-less repo still produces a working landing page instead of breaking.

func Pack

func Pack() core.Pack

Pack returns the repo theme format pack: the engine's markdown parser (for .md → HTML) plus the catch-all source parser (every other text file → line-numbered page), the theme, ignore defaults, and the hooks that default layouts, build the optional README home, rewrite in-repo links, and assemble the file-tree sidebar.

The two parsers layer cleanly: source claims a curated set of text extensions and extensionless names, none of which is *.md, so Markdown falls through to the markdown parser's own extension claim. Anything neither claims (images, PDFs, unknown/binary files) stays an asset the engine copies verbatim — so README images render and files stay downloadable.

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. A repo's Markdown is written for the GitHub view — "see [main.go](./main.go)" or "[the schema](db/schema.sql)" — so this hook resolves each relative href against the page's source location and, when the target file rendered as a page (Markdown or source), rewrites the href to that page's relative URL. Absolute URLs, anchors, mailto, and links to files that aren't pages (e.g. images the engine copied as assets) pass through untouched. This is what makes browsing the repo — and -strict-links — viable over an unmodified checkout.

func Run

func Run(repoPath string, opts Options) error

Run builds (or serves) the repo site for a repository. Discovery runs over the repo itself — the parsers claim files by extension/name — 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: "Repository")
	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-repo site build.