soothfast-site API reference#

Generated by cargo soothfast docs reference Measurements and verified claims come from the latest baseline; CI gates them.

soothfast_site#

BuildInput ^struct#

pub struct BuildInput

BuildReport ^struct#

pub struct BuildReport

SiteConfig ^struct#

pub struct SiteConfig

SitePlugin ^trait#

pub trait SitePlugin

soothfast_site::build#

build ^function#

pub fn build(input: &BuildInput) -> Result<BuildReport, String>

Build the whole site. Any page failing to render fails the build — a half-broken published site is worse than a red command.

soothfast_site::color#

Role ^struct#

pub struct Role

A role's light and dark tones together, as derived from one seed color.

RoleTones ^struct#

pub struct RoleTones

One Material-style color role, resolved to concrete hex values for a single scheme (light or dark).

contrast ^function#

pub fn contrast(a: (u8, u8, u8), b: (u8, u8, u8)) -> f64

WCAG contrast ratio between two colors, >= 1.0.

generate_theme_css ^function#

pub fn generate_theme_css( primary: Option<&str>, secondary: Option<&str>, tertiary: Option<&str>, background: Option<&str>, ) -> Result<String, String>

Generate a theme-vars.css override for whichever [site.theme] seeds are set, covering :root, the OS-dark media query, and the explicit [data-theme] toggle — mirroring tokens.css's own structure so it can simply be linked after it.

parse_hex ^function#

pub fn parse_hex(s: &str) -> Result<(u8, u8, u8), String>

Parse a #rgb, #rrggbb, or bare rrggbb/rgb hex string into (r, g, b) bytes.

relative_luminance ^function#

pub fn relative_luminance(rgb: (u8, u8, u8)) -> f64

WCAG relative luminance, 0.0 (black) .. 1.0 (white).

role_from_seed ^function#

pub fn role_from_seed(seed: (u8, u8, u8), bg_light: (u8, u8, u8), bg_dark: (u8, u8, u8)) -> Role

Derive a full light+dark Material role from one seed hex color, given the page's light and dark background tones (see tones_for_scheme for how a single scheme's tones are computed).

to_hex ^function#

pub fn to_hex(rgb: (u8, u8, u8)) -> String

Render a channel triple as #RRGGBB, the form CSS custom properties and the theme files are written in.

soothfast_site::config#

NavGroup ^struct#

pub struct NavGroup

One nav group in the sidebar: a titled list of markdown pages.

ThemeConfig ^struct#

pub struct ThemeConfig

The [site.theme] section: seed hex colors for the brand roles. Any unset field keeps the built-in "gauge indigo" default from tokens.css. When at least one is set, the build generates _soothfast/theme-vars.css with the full light+dark Material role set derived from each seed (see crate::color::role_from_seed).

parse ^function#

pub fn parse(text: &str) -> Result<SiteConfig, String>

Parse soothfast.toml text into a config. Unknown keys under [site] are errors: silently ignored config is how sites drift from intent.

soothfast_site::evidence#

Evidence ^struct#

pub struct Evidence

Evidence renderer over one baseline + the bind lockfile.

soothfast_site::highlight#

highlight ^function#

pub fn highlight(lang: &str, code: &str) -> String

Highlight code for lang. Always returns escaped HTML.

soothfast_site::md#

CodeHook ^type_alias#

pub type CodeHook<'a> = &'a dyn Fn(&str, &[String], &str) -> Option<String>

Custom renderer for one fenced block: (lang, tags, code) → HTML, or None to fall back to the default <pre> + highlight rendering.

Heading ^struct#

pub struct Heading

One collected heading, for the on-page table of contents.

Options ^struct#

pub struct Options<'a>

Render hooks: link rewriting and custom code-block rendering, so the build pipeline (and plugins) stay out of the parser.

Rendered ^struct#

pub struct Rendered

A rendered page body.

code_html ^function#

pub fn code_html(lang: &str, tags: &[String], code: &str) -> String

Default fenced-block rendering: instrument-panel <figure> with a language label and highlighted body.

render ^function#

pub fn render(md: &str, opts: &Options) -> Result<Rendered, String>

Render one markdown document.

soothfast_site::nav#

Missing ^enum#

pub enum Missing

What to do about a nav entry naming a page the build did not find.

The right answer depends on what the build is for. Publishing a sidebar that links nowhere is drift and should fail. Writing docs is a different activity: the page you are about to add does not exist yet, and stopping the dev server over it helps nobody.

PageMeta ^struct#

pub struct PageMeta

Minimal facts about a discovered page, gathered before rendering.

build ^function#

pub fn build( cfg: &SiteConfig, pages: &[PageMeta], missing: Missing, ) -> Result<(Value, Vec<String>), String>

Resolve nav groups to template data, plus any warnings raised.

Explicit nav wins over the automatic layout. A page it names that the build did not find is handled per [Missing].

href ^function#

pub fn href(base: &str, route: &str) -> String

base + route, with the empty result mapped to ./ (a valid link to the current directory; an empty href reloads the page instead).

route_for ^function#

pub fn route_for(src: &str) -> String

Route for a docs-relative markdown path: pretty directory URLs.

with_current ^function#

pub fn with_current(nav: &Value, route: &str, base: &str) -> Value

Copy of the nav with current: true stamped on the active page and a ready-to-use href per page (relative to the page being rendered), so the template highlights and links without any logic of its own.

soothfast_site::plugin#

PageRecord ^struct#

pub struct PageRecord

A fully rendered page, as seen by end-of-build events.

PageRef ^struct#

pub struct PageRef<'a>

Identity of the page an event concerns.

page_html ^function#

pub fn page_html( plugins: &[Box<dyn SitePlugin>], page: &PageRef, mut html: String, ) -> Result<String, String>

Run one HTML-rewrite pass through all plugins, in order.

page_markdown ^function#

pub fn page_markdown( plugins: &[Box<dyn SitePlugin>], page: &PageRef, mut md: String, ) -> Result<String, String>

Run one markdown-rewrite pass through all plugins, in order.

soothfast_site::search#

Search ^struct#

pub struct Search

Search index builder.

soothfast_site::serve#

Server ^struct#

pub struct Server

A bound dev server, not yet running (split from run so callers and tests can learn the actual address before the loop starts).

soothfast_site::template#

Includes ^trait#

pub trait Includes

Resolves {% include %} names to template text (backed by the theme).

escape ^function#

pub fn escape(s: &str) -> String

Escape text for HTML element and attribute contexts.

render ^function#

pub fn render(source: &str, ctx: &Value, includes: &dyn Includes) -> Result<String, String>

Render source against ctx. Values are looked up by dot path (page.title); a bare . names the current for item.

soothfast_site::theme#

Theme ^struct#

pub struct Theme

A resolved theme: defaults plus user overrides.

soothfast_site::toml#

TomlValue ^enum#

pub enum TomlValue

A parsed TOML scalar, string array, or inline table.

logical_lines ^function#

pub fn logical_lines(text: &str) -> Vec<(usize, String)>

Comment-stripped, non-empty logical lines with their 1-based numbers. A line whose [ array is still open pulls in following lines, so multi-line arrays parse as one key = value.

parse_string ^function#

pub fn parse_string(s: &str) -> Result<(String, usize), String>

Parse a leading double-quoted string; returns (content, bytes consumed).

parse_value ^function#

pub fn parse_value(s: &str) -> Result<TomlValue, String>

Parse a scalar value: string, bool, or string array.