render

Documentation

Overview

Package render implements the leafpress-render bridge: a pure stdin→stdout JSON transform that renders a set of published pages (a "garden") into full HTML documents, an index page, and theme CSS. It performs no filesystem, network, or database access.

The input is one envelope: a shared `config` object (identical to the CLI's leafpress.json), a `render` block of host-only concerns, the `content` to render, and `options`. See docs/05_RENDERER_CONTRACT.md.

Index

• type Content
• type FooterAttribution
• type Input
• type InputError
  • func (e *InputError) Error() string
• type InputPage
• type Options
• type Output
  • func Render(in *Input) (*Output, error)
  • func Run(raw []byte) (*Output, error)
• type OutputArtifact
• type OutputPage
• type OutputSection
• type OutputTagPage
• type OutputTags
• type RenderOpts

Types

type Content

type Content struct {
	Pages []InputPage `json:"pages"`
	// StyleCSS is the in-memory counterpart of the CLI project's style.css.
	StyleCSS string `json:"styleCSS"`
	// Assets declares the user assets the caller will serve alongside the
	// rendered site (custom font files under static/fonts/, and in the future
	// other referenced static files). Entries are validated with the shared
	// manifest rules and merged into the output manifest; an entry whose
	// effective output path collides with a built-in replaces it (the
	// favicon-override rule).
	Assets []assets.Asset `json:"assets"`
}

Content is the renderable input a CLI build would read from disk.

type FooterAttribution

type FooterAttribution struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

FooterAttribution is renderer-only host branding. It is deliberately structured instead of accepting raw HTML or script content.

type Input

type Input struct {
	// ContractVersion is optional; 0 means latest. An unknown version is
	// rejected rather than guessed at.
	ContractVersion int `json:"contractVersion"`
	// Config is the shared configuration object — the same schema the CLI
	// reads from leafpress.json. Absent/empty renders the default site.
	Config json.RawMessage `json:"config"`
	// Render holds the only host-only concerns: the garden identity slug and
	// optional white-label footer attribution.
	Render RenderOpts `json:"render"`
	// Content carries the in-memory equivalents of the filesystem inputs a
	// CLI build reads: the pages, the stylesheet, and declared user assets.
	Content Content `json:"content"`
	// Options carries render toggles.
	Options Options `json:"options"`
}

Input is the top-level JSON object read from stdin.

type InputError

type InputError struct {
	// contains filtered or unexported fields
}

InputError marks failures caused by invalid input (exit code 1), as opposed to internal render failures (exit code 2).

func (*InputError) Error

func (e *InputError) Error() string

type InputPage

type InputPage struct {
	Slug        string   `json:"slug"`
	Title       string   `json:"title"` // optional; defaults to Slug
	Markdown    string   `json:"markdown"`
	Tags        []string `json:"tags"`
	CreatedAt   string   `json:"createdAt"` // optional RFC3339
	UpdatedAt   string   `json:"updatedAt"` // optional RFC3339
	Description string   `json:"description"`
	Growth      string   `json:"growth"`
	TOC         *bool    `json:"toc"`
	Image       string   `json:"image"`
	ReadingTime *int     `json:"readingTime"`
	// IsIndex marks a section home (the CLI's _index.md): Slug is the
	// section path itself, Markdown becomes the intro above the child
	// listing. An IsIndex page with slug "" is the garden home.
	IsIndex bool `json:"isIndex"`
	// Sort orders the child listing of an index page: date (default) |
	// title | growth. Mirrors the _index.md `sort` frontmatter key.
	Sort string `json:"sort"`
	// ShowList toggles the child listing of an index page (default true).
	// Mirrors the _index.md `showList` frontmatter key.
	ShowList *bool `json:"showList"`
}

InputPage is a single published page. Slugs may carry path segments ("essays/my-post"); section membership derives from the slug's directory, exactly like the CLI build.

type Options

type Options struct {
	// EmitAssets requests base64 artifacts for the built-in assets the
	// rendered site requires. The asset manifest is always emitted; bytes are
	// opt-in so routine renders stay small. Synchronization is hash-driven per
	// manifest entry — the registry ID alone is never a valid skip signal,
	// because the manifest is a theme-dependent subset.
	EmitAssets bool `json:"emitAssets"`
}

Options carries render toggles.

type Output

type Output struct {
	Pages    []OutputPage    `json:"pages"`
	Index    string          `json:"index"`
	Sections []OutputSection `json:"sections"`
	Tags     OutputTags      `json:"tags"`
	CSS      string          `json:"css"`
	// AssetManifest is the combined manifest of every asset the rendered
	// site requires: referenced built-ins plus caller-declared assets, with
	// caller entries replacing built-ins on output-path collision. Metadata
	// only, never bytes. Hosted consumers materialize each entry through
	// their own storage using the content hash; built-in entries also
	// appear as base64 artifacts when the input sets options.emitAssets.
	AssetManifest assets.Manifest `json:"assetManifest"`
	// AssetRegistryID identifies the built-in registry snapshot the manifest
	// came from (content-derived). It is a change signal only — the manifest
	// is a theme-dependent subset, so synchronization stays hash-driven per
	// entry, never keyed on this ID.
	AssetRegistryID string           `json:"assetRegistryId"`
	Artifacts       []OutputArtifact `json:"artifacts"`
	Warnings        []string         `json:"warnings"`
}

Output is the top-level JSON object written to stdout.

func Render

func Render(in *Input) (*Output, error)

Render validates the input and produces rendered output.

func Run

func Run(raw []byte) (*Output, error)

Run decodes raw JSON input and renders it. Errors of type *InputError indicate invalid input; any other error is an internal failure.

type OutputArtifact

type OutputArtifact struct {
	Path        string `json:"path"`
	Content     string `json:"content"`
	ContentType string `json:"contentType"`
	// Encoding says how Content encodes the file bytes and is authoritative
	// (never sniff): generated site artifacts are always "utf8"; asset
	// artifacts emitted under options.emitAssets are always "base64" regardless
	// of MIME type (OFL license texts included).
	Encoding string `json:"encoding"`
}

OutputArtifact is a filesystem-free generated site file. Path uses the exact CLI filename so consumers can store/serve artifacts generically.

type OutputPage

type OutputPage struct {
	Slug string `json:"slug"`
	HTML string `json:"html"`
}

OutputPage is a rendered page document. Index pages appear here too, rendered as their section's home.

type OutputSection

type OutputSection struct {
	Slug string `json:"slug"`
	HTML string `json:"html"`
}

OutputSection is an auto-generated home for a section that has no index page (the CLI's auto-index), served at {baseUrl}/<slug>/.

type OutputTagPage

type OutputTagPage struct {
	Tag  string `json:"tag"`
	HTML string `json:"html"`
}

OutputTagPage is a rendered page listing everything under one tag, served at {baseUrl}/tags/<tag>/.

type OutputTags

type OutputTags struct {
	Index string          `json:"index"`
	Pages []OutputTagPage `json:"pages"`
}

OutputTags holds the rendered tag index and per-tag pages. When no page carries any tag, Index is "" and Pages is empty (mirroring the CLI, which skips the tags section entirely in that case).

type RenderOpts

type RenderOpts struct {
	// Slug is the hosted garden's identity/routing key. It has no natural
	// default; when omitted it defaults to "garden" with a warning.
	Slug string `json:"slug"`
	// FooterAttribution is renderer-only white-label branding, deliberately
	// structured instead of accepting raw HTML or script content.
	FooterAttribution *FooterAttribution `json:"footerAttribution,omitempty"`
}

RenderOpts holds renderer/hosting concerns that a filesystem build never needs.