Stati Documentation

Stati Glossary

Key terms and concepts used throughout Stati documentation.

Filesystem-based Routing

Stati maps your directory structure in site/ directly to URL paths. A file at site/docs/intro.md becomes /docs/intro/.

Incremental Static Generation (ISG)

A build optimization that caches rendered pages and only rebuilds when content changes or TTL expires. Configured via isg in stati.config.ts.

Eta Templates

Stati’s templating engine. Eta files (.eta) support layouts, partials, filters, and embedded JavaScript. The main layout is typically layout.eta.

Layout

A reusable template wrapper that provides consistent structure (header, footer, navigation). Pages specify their layout via frontmatter: layout: layout.eta.

Layout Inheritance

Stati’s hierarchical layout system where more specific layouts override parent directory layouts. A layout.eta in a subdirectory completely replaces the root layout for pages in that directory. For example, site/blog/layout.eta overrides site/layout.eta for all pages under /blog/. Section layouts must be complete HTML documents.

Partials

Reusable template fragments stored in underscore-prefixed directories (e.g., _partials/, _components/). Include them via stati.partials.header. Stati uses a flat namespace for partials - the file name becomes the partial name regardless of subdirectory.

Callable Partials

An advanced partial usage pattern that allows passing data to partials like function arguments. Instead of just <%~ stati.partials.header %>, you can call:

<%~ stati.partials.card({ title: 'Hello', featured: true }) %>

Data is accessed inside the partial via stati.props. Callable partials enable component-like reusability where the same partial renders different content based on props.

Examples:

  • Simple: <%~ stati.partials.header %>
  • With props: <%~ stati.partials.card({ title: 'My Card', url: '/page' }) %>
  • In loops: <% posts.forEach(post => { %> <%~ stati.partials.card({ title: post.title }) %> <% }) %>

Inside the partial:

<div class="card">
  <h2><%= stati.props.title %></h2>
  <% if (stati.props.featured) { %>
    <span class="badge">Featured</span>
  <% } %>
</div>

Frontmatter

YAML metadata at the top of Markdown files. Controls title, description, layout, order, and SEO settings.

Hierarchical Partials

Partials are discovered upward from the current page’s directory to the root. A page can access partials from its own directory and all parent directories, but not from child directories. For example, a root layout can only access site/_partials/, while a blog layout can access both site/_partials/ AND site/blog/_partials/. More specific partials (deeper in hierarchy) override less specific ones with the same name.

Template Context (stati)

The object passed to every Eta template containing:

  • stati.site – Site configuration
  • stati.page – Current page data and frontmatter
  • stati.content – Rendered HTML content
  • stati.nav – Navigation helpers and tree
  • stati.partials – Partial templates accessible as properties (rendered markup) or callable functions (with props)

SEO Metadata

Automatically generated HTML tags for search engines and social sharing. Includes title, description, canonical, Open Graph, Twitter Cards, and JSON-LD structured data.

stati.config.ts

The TypeScript configuration file at your project root. Defines site metadata, Markdown plugins, Eta filters, ISG settings, and build hooks.

defineConfig

A helper function from @stati/core that provides type-safe configuration. Wraps your Stati config object for IntelliSense and type checking.

Build Hooks

Extension points (beforeAll, afterAll, beforeRender, afterRender) that let you inject custom logic at various stages of the build process.

esbuild

The underlying JavaScript bundler that powers Stati’s TypeScript compilation. Provides near-instant build times for client-side code.

Development Server

Stati’s local server (stati dev) with hot reload, file watching, and incremental builds for efficient development.

TTL (Time To Live)

The duration in seconds that cached content remains valid before requiring a rebuild. Configured via isg.ttlSeconds.

Cache Invalidation

The process of marking cached entries as stale using stati invalidate with patterns like tag:, path:, glob:, or age:.

Draft

A page marked with draft: true in frontmatter, excluded from production builds unless --include-drafts is used.

Dynamic Attribute Values

A templating pattern required when embedding dynamic content in HTML attributes. Eta doesn’t support partial interpolation like mixing static and dynamic text in attributes. Instead, use template literals for the entire attribute value, or use stati.propValue() for space-separated values like multiple CSS classes. See Dynamic Attribute Values in the templates documentation.

Collection

A group of pages in a directory, often with shared layout and navigation (e.g., blog posts, documentation sections).

Eta Filters

Custom functions registered in stati.config.ts under eta.filters that transform values in templates (e.g., date formatting, slugify).

stati.nav

The navigation helper object available in templates with methods:

  • getTree() – Returns the full navigation tree
  • findNode(path) – Finds a navigation node by path or URL
  • getChildren(path) – Gets child nodes of a path
  • getParent(path?) – Gets the parent node (defaults to current page)
  • getSiblings(path?, includeSelf?) – Gets sibling nodes
  • getSubtree(path) – Gets a subtree starting from a path
  • getBreadcrumbs(path?) – Gets the breadcrumb trail
  • getCurrentNode() – Gets the current page’s navigation node

A navigation tree node containing title, url, path, order, publishedAt, children, and isCollection properties.

Sitemap

An XML file listing all site URLs with metadata, auto-generated during production builds when sitemap.enabled is true.

RSS Feed

An XML file for content syndication, configured via rss.feeds with content patterns, filters, and item mapping.

Scaffolder (create-stati)

The interactive CLI tool that creates new Stati projects with styling options, TypeScript support, and Git initialization.

  • FAQ – Frequently asked questions about Stati
  • Core Concepts – Deep dive into Stati’s architecture