render

Documentation

Overview

Package render expands directives in one markdown document into plain markdown at build time (docs/SPEC.md §9, §22 `ds render`). Citations become permalinks, `ds:cfg` becomes the current value, block-position `ds:block` becomes the live code, inline defs become their text, claims and defs disappear. The repository never holds a copy of a block; this is where the copy is made, and only in the built output.

Render never fails on a bad directive. It leaves the line as written, records a Note with the line number, and continues, so one broken cite cannot take a site build down. The checker is what fails a build.

Index

• Constants
• Variables
• func Closer(prefix, shortHash string) string
• func Provider(addr, source string) string
• func RenderNodes(in Input, opts Options) ([]Node, []Note)
• func Value(b block.Block) (string, bool)
• type Input
• type Node
• type Note
  • func Fragment(b block.Block, ref block.Reference, prefix string, maxLines int) (text string, ok bool, notes []Note)
  • func Render(in Input, opts Options) ([]byte, []Note)
• type Options
• type RunResult
• type VerbRenderer

Constants

const (
	NodeText  = "text"  // an untouched source line
	NodeProse = "prose" // a prose line with inline directives expanded
	NodeBlock = "block" // the output of a block-position directive
)

Node kinds for RenderNodes (§37.3 Renderer): a custom renderer receives the document as a sequence of nodes instead of joined markdown.

const (
	FormatRaw     = "raw"
	FormatCode    = "code"
	FormatQuote   = "quote"
	FormatHost    = "host"
	FormatLink    = "link"
	FormatCompact = "compact"
)

Format values for `ds:cfg` (§9.3).

const (
	ProviderGitHub      = "github"
	ProviderOnePassword = "1password"
	ProviderAWS         = "aws"
	ProviderGCP         = "gcp"
	ProviderVault       = "vault"
	ProviderEnv         = "env"
	ProviderFile        = "file"
)

Providers a secret address can name (§12).

const DefaultMaxLines = 40

DefaultMaxLines mirrors include.max_lines (§9.2).

const DefaultPermalink = "{file}#L{start}-L{end}"

DefaultPermalink is used when Options.Permalink is empty.

Variables

var FormatValues = []string{FormatRaw, FormatCode, FormatQuote, FormatHost, FormatLink, FormatCompact}

FormatValues is the canonical list.

Functions

func Closer

func Closer(prefix, shortHash string) string

Closer is the line that ends a repo-mode region and records the block hash it was rendered from.

func Provider

func Provider(addr, source string) string

Provider names the secret provider from an address shape, falling back to the declared source (§12). Empty when neither says.

func RenderNodes

func RenderNodes(in Input, opts Options) ([]Node, []Note)

RenderNodes is Render as a node sequence, for a custom Renderer.

func Value

func Value(b block.Block) (string, bool)

Value returns a block's single-line value: its content when it is exactly one line. Multi-line blocks have no value (§9.3).

Types

type Input

type Input struct {
	Doc  string
	Src  []byte
	Defs []block.Block
}

Input is the document plus every definition it may cite.

type Node

type Node struct {
	Kind string `json:"kind"`
	Line int    `json:"line"`
	Text string `json:"text"`
}

Node is one rendered unit; Line is the source line it came from.

type Note

type Note struct {
	Line    int
	Message string
}

Note is a rendering problem: the line it happened on and what was wrong.

func Fragment

func Fragment(b block.Block, ref block.Reference, prefix string, maxLines int) (text string, ok bool, notes []Note)

Fragment renders the repo-mode copy of a block-position reference: the caption and fence exactly as `refresh` writes them and `check` expects them (§9.2). Permalinks inside a committed copy are always repo-relative, never commit-pinned, so a new commit does not make every copy tampered. ok is false when the reference cannot render (missing def, secret, out of range); notes carry why.

func Render

func Render(in Input, opts Options) ([]byte, []Note)

Render expands in.Src and returns the result with notes, sorted by line.

type Options

type Options struct {
	Prefix string
	// Permalink is a template with {sha} {file} {start} {end}; empty renders
	// a repo-relative `file#Lstart-Lend`.
	Permalink string
	Commit    string
	MaxLines  int
	// Env picks among per-environment defs for cites that do not say.
	Env string
	Now time.Time
	// Link replaces Permalink entirely; the one escape hatch for hosts whose
	// URLs the template cannot express.
	Link func(b block.Block) string
	// Snapshot returns the block's content at a commit, for `at=`.
	Snapshot func(id, sha string) (string, bool)
	// Records answers `ds:table`: rows as maps keyed by column.
	Records func(args map[string]string) ([]map[string]string, error)
	// Runs maps a doc line to the last `ds:run` result recorded there.
	Runs map[int]RunResult
	// Verbs renders plugin verbs by name.
	Verbs map[string]VerbRenderer
}

Options tunes a render. Hooks are optional and degrade honestly: without Snapshot an `at=` cite renders as a link with an "as of" badge and no code; without Records a `ds:table` renders its `empty=` text.

type RunResult

type RunResult struct {
	Output string
	OK     bool
	At     time.Time
}

RunResult is the last recorded outcome of a `ds:run`, keyed by doc line by the caller. The renderer runs nothing (§9.4).

type VerbRenderer

type VerbRenderer func(ref block.Reference, inline bool) (text string, ok bool, err error)

VerbRenderer renders a plugin verb (§9.9, §37.3 Verb.Render). inline is true for a link in prose, false for block position; ok=false leaves the source untouched and records a note with the error.