API Reference

This page documents the public API of the three library crates: taxus-domain (the model), taxus_lib (the generator library, crate taxus-generator) and taxus-common (islands and search). Terms are defined in the Glossary. cargo doc --workspace --no-deps --open builds the full rustdoc, which is the authoritative reference; this page is the map.

taxus-domain Crate

The pure data model. No I/O. See The Site Tree, Identity and Derivations.

identity Module

#![allow(unused)]
fn main() {
pub struct Slug(String);      // one validated URL segment
pub struct NodePath(Vec<Slug>); // slugs from the root to a node
pub struct UrlPath(String);   // the derived address, "/blog/my-post/"
pub enum IdentityError { Empty, Slash { s }, DotSegment { s }, ControlCharacter { s } }
}

schema Module

#![allow(unused)]
fn main() {
pub struct Frontmatter {
    pub title: String,                    // default ""
    pub description: Option<String>,
    pub tagline: Option<String>,
    pub date: Option<NaiveDate>,
    pub template: Option<String>,
    pub draft: bool,
    pub summary: Option<String>,
    pub slug: Option<String>,
    pub aliases: Vec<String>,
    pub tags: Vec<String>,
    pub categories: Vec<String>,
    pub series: Option<String>,
    pub extra: Option<toml::Value>,
    pub sort_by: SortBy,                  // default Date
    pub paginate_by: usize,               // 0 = no pagination
    pub paginate_template: Option<String>,
    pub weight: i32,
    pub pages_from: Vec<String>,          // donor sections, "blog"
    pub updated: Option<NaiveDate>,
    pub hero_image: Option<String>,
    pub hero_alt: Option<String>,
}

pub enum SortBy { Date, Title, Weight, None }
}

tree Module

#![allow(unused)]
fn main() {
pub struct SiteTree { pub root: SectionNode }

pub struct SectionNode {
    pub path: NodePath,
    pub content_file: Option<PathBuf>,   // "blog/_index.md", or None
    pub meta: Frontmatter,
    pub body: Option<String>,
    pub pages: Vec<PageNode>,            // direct children, by slug
    pub subsections: Vec<SectionNode>,   // direct children, by slug
}

pub struct PageNode {
    pub path: NodePath,
    pub content_file: PathBuf,           // "blog/2026-04-03-project-launch.md"
    pub meta: Frontmatter,
    pub body: String,
}

pub enum TreeError { Duplicate { path }, Collision { path, kind }, RootReserved, Identity(IdentityError) }
}

derivation Module

#![allow(unused)]
fn main() {
pub enum Node<'a> { Section(&'a SectionNode), Page(&'a PageNode) }
}

The crate root re-exports Frontmatter, SortBy, NodePath, Slug, UrlPath, PageNode, SectionNode, SiteTree, SiteTreeBuilder and TreeError.

taxus-common Crate

Shared by the generator (build-time rendering) and the client (browser hydration).

components Module

search Module

SearchDocument

#![allow(unused)]
fn main() {
pub struct SearchDocument {
    pub id: u32,
    pub title: String,
    pub path: String,
    pub summary: String,
    pub tags: Vec<String>,
    pub categories: Vec<String>,
}
}

SearchIndex

#![allow(unused)]
fn main() {
pub struct SearchIndex {
    pub documents: BTreeMap<u32, SearchDocument>,
    pub index: HashMap<String, Vec<(u32, f32)>>,
}
}

Helper Functions

#![allow(unused)]
fn main() {
pub fn tokenize(text: &str) -> Vec<String>  // lowercase tokens, words shorter than 3 characters dropped
pub fn stem(tokens: &[String]) -> Vec<String> // English Porter stemmer
}

taxus-generator Crate (taxus_lib)

Re-exports

#![allow(unused)]
fn main() {
pub use config::{BuildConfig, ImageConfig, SiteConfig, SiteMeta};
pub use content::{ContentSource, FilesystemContentSource, Frontmatter, Page};
pub use templates::{HeroContext, PageContext, SectionContext, SiteContext, TemplateContext, TemplateRenderer, TeraRenderer};
pub use assets::{AssetProcessor, AssetReport, ScssProcessor, StaticCopier};
pub use build::{BuildReport, SiteBuilder};
pub use feed::{FeedConfig, FeedEntry, FeedGenerator};
pub use highlighting::{CodeHighlighter, LanguageRegistry};
pub use images::{ImageProcessor, ImageRegistry, ProcessedImage, render_picture};
pub use init::{InitOptions, InitReport, InitScaffolder};
pub use routes::{RouteDiscovery, RouteInfo, RouteKind, RouteRegistry};
pub use error::{AssetError, ContentError, FeedError, GeneratorError, ImageError, InitError, Result, RouteError, TemplateError};
}

config Module

SiteConfig

#![allow(unused)]
fn main() {
pub struct SiteConfig {
    pub site: SiteMeta,
    pub build: BuildConfig,
    pub feed: FeedConfig,
    pub highlight: HighlightConfig,
    pub images: ImageConfig,
    pub markdown: MarkdownConfig,
    pub base_dir: PathBuf,
}
}

SiteMeta

#![allow(unused)]
fn main() {
pub struct SiteMeta {
    pub name: String,
    pub base_url: String,
    pub description: Option<String>,
    pub author: Option<String>,
}
}

BuildConfig

#![allow(unused)]
fn main() {
pub struct BuildConfig {
    pub content_dir: PathBuf,    // default: "content"
    pub output_dir: PathBuf,     // default: "dist"
    pub static_dir: PathBuf,     // default: "static"
    pub styles_dir: PathBuf,     // default: "styles"
    pub templates_dir: PathBuf,  // default: "templates"
}
}

FeedConfig

#![allow(unused)]
fn main() {
pub struct FeedConfig {
    pub rss_enabled: bool,       // default: true
    pub atom_enabled: bool,      // default: false
    pub limit: usize,            // default: 20 (0 is treated as 20)
    pub full_content: bool,      // default: false
    pub title: Option<String>,
    pub rss_path: Option<String>,   // default file: feed.xml
    pub atom_path: Option<String>,  // default file: feed.atom
    pub sections: Vec<String>,   // default: [] (whole site)
}
}

HighlightConfig, ImageConfig, MarkdownConfig

#![allow(unused)]
fn main() {
pub struct HighlightConfig { pub enabled: bool /* true */, pub class_prefix: String /* "hl-" */ }
pub struct ImageConfig { pub widths: Vec<u32>, pub quality: u8, pub format: String, pub output_dir: PathBuf }
pub struct MarkdownConfig { pub insert_anchor_links: bool }
}

content Module

Frontmatter and SortBy are re-exported from taxus-domain.

Page

One parsed content file (page or index file).

#![allow(unused)]
fn main() {
pub struct Page {
    pub frontmatter: Frontmatter, // page metadata
    pub raw_content: String,      // the Markdown body
}
}

A Page is the parsed form of one tree node's document — exactly what discovery read from disk, nothing computed. The build constructs them from the tree in stage 3; the served URL lives on ProcessedPage, never here.

split_date_prefix

#![allow(unused)]
fn main() {
pub fn split_date_prefix(stem: &str) -> (&str, Option<NaiveDate>)
}

Strips a valid YYYY-MM-DD- prefix from a file stem and returns the date; a stem that is only a date is returned unchanged.

Sections

Sections are not a content type. A directory is a taxus_domain::SectionNode in the SiteTree built by RouteDiscovery::discover_tree; see The Site Tree.

TaxonomyKind, TaxonomyTerm, TaxonomyMap

#![allow(unused)]
fn main() {
pub enum TaxonomyKind { Tag, Category, Series }
pub struct TaxonomyTerm { pub kind, pub name: String, pub slug: String, pub page_count: usize, pub page_paths: Vec<String> /* content files */ }
pub struct TaxonomyMap { /* terms per kind */ }
}

ContentSource Trait

#![allow(unused)]
fn main() {
pub trait ContentSource: Send + Sync {
    fn load(&self, path: &Path) -> Result<String>;
    fn exists(&self, path: &Path) -> bool;
    fn list(&self) -> Result<Vec<PathBuf>>;
}
}

FilesystemContentSource

routes Module

RouteKind

#![allow(unused)]
fn main() {
pub enum RouteKind { Page, Section }
}

RouteInfo

#![allow(unused)]
fn main() {
pub struct RouteInfo {
    pub path: String,          // URL path, "/blog/my-post/"
    pub content_file: PathBuf,
    pub output_file: PathBuf,  // "blog/my-post/index.html"
    pub kind: RouteKind,
}
}

RouteRegistry

RouteDiscovery

slugify

#![allow(unused)]
fn main() {
pub fn slugify_segment(segment: &str) -> String  // "My Créative Post" -> "my-creative-post" (node paths; ASCII)
pub fn slugify_path(relative: &str) -> String    // "blog/My Old Post" -> "blog/my-old-post"
pub fn slugify_term(name: &str) -> String        // "Café" -> "café" (taxonomy terms; keeps non-ASCII letters)
}

templates Module

TemplateRenderer Trait

#![allow(unused)]
fn main() {
pub trait TemplateRenderer: Send + Sync {
    fn render(&self, template: &str, context: &TemplateContext) -> Result<String, TemplateError>;
    fn register_template(&mut self, name: &str, content: &str) -> Result<(), TemplateError>;
    fn has_template(&self, name: &str) -> bool;
    fn load_templates(&mut self, dir: &Path) -> Result<(), TemplateError>;
}
}

TeraRenderer

TemplateContext

#![allow(unused)]
fn main() {
pub struct TemplateContext {
    pub page: Option<PageContext>,
    pub section: Option<SectionContext>,
    pub site: SiteContext,
    pub now: NowContext,
    pub extra: HashMap<String, serde_json::Value>,
}
}

PageContext

#![allow(unused)]
fn main() {
pub struct PageContext {
    pub title: String,
    pub description: Option<String>,
    pub tagline: Option<String>,
    pub path: String,             // URL path
    pub permalink: String,        // base_url + path
    pub content: String,          // rendered HTML
    pub raw_content: String,
    pub date: Option<String>,     // ISO 8601
    pub draft: bool,
    pub summary: String,
    pub word_count: usize,
    pub reading_time: usize,
    pub toc: Vec<TocEntry>,
    pub tags: Vec<String>,
    pub categories: Vec<String>,
    pub series: Option<String>,
    pub weight: i32,
    pub hero: Option<HeroContext>,
}
}

HeroContext

#![allow(unused)]
fn main() {
pub struct HeroContext { pub src: String, pub srcset: String, pub width: u32, pub height: u32, pub alt: String, pub mime_type: String }
}

SectionContext and SubsectionContext

#![allow(unused)]
fn main() {
pub struct SectionContext {
    pub title: String,
    pub description: Option<String>,
    pub path: String,
    pub permalink: String,
    pub content: Option<String>,
    pub toc: Vec<TocEntry>,
    pub pages: Vec<PageContext>,          // the listing
    pub pagination: Option<PaginationContext>,
    pub subsections: Vec<SubsectionContext>,
}

pub struct SubsectionContext { pub title: String, pub description: Option<String>, pub path: String, pub permalink: String }
}

PaginationContext

#![allow(unused)]
fn main() {
pub struct PaginationContext {
    pub current: usize,
    pub total: usize,
    pub per_page: usize,
    pub total_items: usize,
    pub prev: Option<String>,
    pub next: Option<String>,
    pub first: String,
    pub last: String,
}
}

TaxonomyListContext and TaxonomyTermContext

#![allow(unused)]
fn main() {
pub struct TaxonomyListContext { pub kind: String, pub path: String, pub terms: Vec<TaxonomyTermContext> }
pub struct TaxonomyTermContext { pub kind: String, pub name: String, pub slug: String, pub path: String, pub page_count: usize, pub pages: Vec<PageContext> }
}

Both are passed to templates as extra.taxonomy.

SiteContext and NowContext

#![allow(unused)]
fn main() {
pub struct SiteContext { pub name: String, pub base_url: String, pub description: Option<String>, pub author: Option<String> }
pub struct NowContext { pub year: i32 }
}

compute_permalink

#![allow(unused)]
fn main() {
pub fn compute_permalink(base_url: &str, path: &str) -> String
}

build Module

SiteBuilder

BuildReport

#![allow(unused)]
fn main() {
pub struct BuildReport {
    pub pages_rendered: usize,
    pub sections_rendered: usize,
    pub drafts_skipped: usize,
    pub sitemap_urls: usize,
    pub assets: AssetReport,
    pub duration: Duration,
    pub warnings: Vec<String>,
    pub output_dir: PathBuf,
}
}

ProcessedPage and RenderedPage

#![allow(unused)]
fn main() {
pub struct ProcessedPage {
    pub route: RouteInfo,
    pub page: Page,
    pub html_content: String,
    pub toc: Vec<TocEntry>,
    pub hero_image: Option<ProcessedImage>,
}

pub struct RenderedPage {
    pub route: RouteInfo,
    pub content: String,
    pub hero_image: Option<ProcessedImage>,
}
}

build::pipeline functions

assets Module

AssetProcessor Trait

#![allow(unused)]
fn main() {
pub trait AssetProcessor: Send + Sync {
    fn process(&self, src: &Path, dest: &Path, dry_run: bool) -> Result<AssetReport, AssetError>;
    fn handles(&self, path: &Path) -> bool;
    fn name(&self) -> &'static str;
}
}

ScssProcessor

StaticCopier

AssetReport

#![allow(unused)]
fn main() {
pub struct AssetReport {
    pub files_processed: usize,
    pub files_skipped: usize,
    pub errors: Vec<String>,
}
}

images Module

highlighting Module

feed Module

#![allow(unused)]
fn main() {
pub struct FeedConfig { pub title, pub description, pub base_url, pub author, pub author_email, pub language, pub limit: Option<usize>, pub full_content, pub filename }
pub struct FeedEntry { pub title, pub url, pub summary, pub content: Option<String>, pub date: DateTime<Utc>, pub updated, pub author, pub author_email, pub tags }
}

init Module

InitOptions

#![allow(unused)]
fn main() {
pub struct InitOptions {
    pub name: String,
    pub base_url: String,
    pub force: bool,
    pub islands: bool,
}
}

InitScaffolder

InitReport

#![allow(unused)]
fn main() {
pub struct InitReport {
    pub path: PathBuf,
    pub directories_created: usize,
    pub files_created: usize,
    pub created_dirs: Vec<PathBuf>,
    pub created_files: Vec<PathBuf>,
}
}

Helpers

#![allow(unused)]
fn main() {
pub fn is_directory_empty(path: &Path) -> Result<bool>
pub fn derive_site_name(path: &Path) -> String
}

serve Module

DevServer

DevServerConfig

#![allow(unused)]
fn main() {
pub struct DevServerConfig {
    pub host: IpAddr,            // default: 127.0.0.1
    pub port: u16,               // default: 3000
    pub output_dir: PathBuf,
    pub site_dir: PathBuf,
    // ...
}
}

Also exported: browsable_url(SocketAddr) -> String, FileWatcher, WatchEvent, ChangeType, ReloadEvent, WebSocketMessage, inject_live_reload_script, LIVE_RELOAD_SCRIPT.

error Module

GeneratorError

#![allow(unused)]
fn main() {
pub enum GeneratorError {
    Config(Box<ConfigError>),
    Content(Box<ContentError>),
    Template(Box<TemplateError>),
    Asset(Box<AssetError>),
    Route(Box<RouteError>),
    Init(Box<InitError>),
    Serve(Box<ServeError>),
    Feed(Box<FeedError>),
    Image(Box<ImageError>),
    Search(Box<SearchError>),
    Io { path: PathBuf, source: std::io::Error },
    NoContent,
    BrokenInternalLink { file: String, target: String },
    PageRenderFailed { path: String, source: TemplateError },
}
}

Result

#![allow(unused)]
fn main() {
pub type Result<T> = std::result::Result<T, GeneratorError>;
}

telemetry Module