Public API reference

This page summarizes the main API exposed by site-core.

Site builder

Site::builder() creates a SiteBuilder.

Main builder methods:

• content_dir(...): choose the content root, defaulting to content/

• cache_dir(...): choose the incremental-build and asset-cache directory

• page_route_output(...): choose whether page-like routes emit as .../index.html or ...html

• collection::<T>(key): load one typed collection from content/<key>/

• validate_collection::<T, _>(key, validator): run semantic validation after all collections load

• page(path, handler): register one explicit page-like route

• file(path, handler): register one explicit flat-file output

• collection_page::<T, _>(key, "/path/{slug}/", handler): register one route per content entry

• generated_routes(routes, handler): register a computed route family

• markdown_component(tag, component): override one markdown-generated HTML tag

• processor(processor): register a route artifact post-processor

• asset_processor(processor): register an asset post-processor

• build(): load content and return a renderable Site

Route shapes

Use:

• page(...) for known page-like routes and extension-based files such as /sitemap.xml

• file(...) for explicit flat files such as robots.txt or /_headers

• collection_page(...) for the one-entry-one-route case

• generated_routes(...) when content decides which routes exist

PageRouteOutput controls whether page-like routes emit as directory indexes or flat .html files.

Context types

RenderContext:

• reads collections

• reads individual entries by slug or by EntryRef<T>

• renders markdown

• resolves authored assets, concrete image outputs, and responsive image outputs

• probes authored images without decoding their full pixel payload

• inspects ctx.routes()

RouteSourceContext:

• decides which generated routes exist

• reads collections during route expansion

• records dependencies for route-family invalidation

CollectionValidationContext:

• validates frontmatter after collections load

• resolves slug references during validation

• creates source-aware diagnostics

Markdown component context

ComponentProps is passed into markdown component overrides registered through markdown_component(tag, component).

It exposes:

• tag

• attrs

• children

• attr(key)

• asset_url(key)

• image_url(key, output)

• responsive_image(key, output)

• probe_image(key)

That lets markdown component code stay close to the authored tag while still resolving local asset references through the same pipeline used by route handlers.

Route metadata

GeneratedRoute supports:

• GeneratedRoute::new(path, data)

• GeneratedRoute::file(path, data)

• with_source_entry(collection, slug)

• with_attribute(key, value)

RouteInfo exposes:

• path

• source_entries

• attributes

• attribute(key)

• has_attribute(key, value)

• references_collection(key)

• references_entry(key, slug)

Pagination helper

paginate(...) splits owned items into numbered pages and returns PaginationPage<T> values with:

• page_number

• total_pages

• items

It is intentionally narrow. It removes the repeated bookkeeping without hiding route definitions behind a DSL.

Artifacts

Use:

• Artifact::Html

• Artifact::Xml

• Artifact::Json

• Artifact::Text

Artifact kind and output filename are independent. If you need a literal output path, use file(...) or GeneratedRoute::file(...).

Build results

Site::render_to(output_dir) returns a BuildReport.

BuildReport exposes:

• routes: one RouteBuildRecord per route

• assets: one AssetBuildRecord per generated public asset

• removed_outputs: public outputs removed because they no longer belong to the route set

• emitted(): number of routes rendered during this build

• skipped(): number of routes reused from the previous build

• asset_operations(): number of public asset outputs materialized during this build

Route records carry:

• route_path

• output_path

• status

Route status is either:

• RouteBuildStatus::Emitted(BuildReason)

• RouteBuildStatus::Skipped

The current build reasons are:

• NewRoute

• MissingOutput

• ProgramChanged

• HandlerChanged

• OutputPathChanged

• DependencyChanged

• RouteManifestChanged

Asset records carry:

• public_path

• source_path

• status

Asset status is one of:

• AssetBuildStatus::Transformed

• AssetBuildStatus::ReusedCachedObject

• AssetBuildStatus::RestoredPublicCopy

This API is useful when a custom CLI, test, or deployment step needs to distinguish actual work from cache reuse.

Processors

Route processors implement ArtifactProcessor.

They receive:

• the route path

• the route Artifact

Use them for output-level cleanup such as HTML minification or feed-specific rewriting. The built-in IntertagWhitespaceMinifier is the current example.

Asset processors implement AssetProcessor.

They receive:

• an AssetProcessContext

• the final output bytes from the asset pipeline

AssetProcessContext includes:

• the authored source asset path

• the source document when one exists

• the original authored reference string

• whether the output came from a copy or image-transform path

• the final output extension when one exists

Override cache_key() when processor behavior depends on configuration that must invalidate cached asset outputs.

Asset requests

The main image request types re-exported from site-core are:

• ImageOutput

• ResponsiveImageOutput

• ImageFormat

• ImageFit

• BackgroundColor

• ImageProbe

• ImageProbeFormat

Important behavior:

• vector inputs stay vector by default

• rasterize_vector_inputs() is explicit opt-in

• background flattening is part of the request

• cache keys derive from source bytes plus a canonical transform description

• the site-facing API stays agnostic to the source format

• RenderContext::probe_image(...) and ComponentProps::probe_image(...) can inspect authored image format and dimensions without a full image decode