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 = "{rel}#L{start}-L{end}"

DefaultPermalink is used when Options.Permalink is empty. It names the file relative to the rendered page ({rel}), not to the repository root ({file}): a link resolves against the page that holds it, so a root-relative billing/x.go written into docs/billing.md pointed at docs/billing/x.go, which does not exist, on GitHub and on any static host that serves the tree as it is (bug 64).

Variables

var AddressProviderValues = []string{ProviderGitHub, ProviderOnePassword, ProviderAWS, ProviderGCP, ProviderVault}

AddressProviderValues are the providers Provider infers from an address's shape, as opposed to those only a `source=` can name. Each is a provider `ds check --resolve` asks a plugin about without the author saying which, so each must have a plugin shipped beside ds; a test holds the release to that (bug 80).

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

FormatValues is the canonical list.

var ProviderValues = []string{ProviderGitHub, ProviderOnePassword, ProviderAWS, ProviderGCP, ProviderVault, ProviderEnv, ProviderFile}

ProviderValues is the canonical list of the providers above.

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.

A copy of another repository's block names that repository and carries no link (bug 105): its URL comes from the workspace file, which a frozen check does not read, so a linked copy written by refresh would read as tampered in CI.

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} {rel} {start} {end}; empty
	// renders DefaultPermalink, a link relative to the page.
	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
	// ForeignLink is the URL of a block another repository in the workspace
	// defines (block.KeyRepo set): its path is relative to that repository,
	// so the Permalink template, which describes this one, cannot build it.
	// ok=false, or a nil hook, renders the location unlinked with the
	// repository named. Link, when set, still wins.
	ForeignLink func(b block.Block) (url string, ok bool)
	// Snapshot returns the block's content at a commit, for `at=`.
	Snapshot func(id, sha string) (string, bool)
	// SnapshotBlock returns the whole block at a commit, for `at=`: its
	// content, and the position its caption and link name. It takes
	// precedence over Snapshot; with only Snapshot, the link names where
	// the block is today.
	SnapshotBlock func(id, sha string) (block.Block, 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.