Stencila sites are configured in stencila.toml at the root of your workspace. The [site] section lets you control how your published site looks, how content is routed, which interactive features are enabled, and how readers move around it.

This guide is intended as a practical, user-facing companion to the more detailed configuration reference under /docs/config/site/. If you are just getting started, begin here. If you need every field and type, use the reference pages.

Your site configuration goes in the workspace root stencila.toml file.

Many settings can be written either:

For example, search can be enabled with a single boolean:

or configured in more detail:

Stencila validates site configuration strictly. Unknown keys in [site] and its nested tables will cause a configuration parse error, so it is worth checking field names carefully if a config does not load.

You do not need to configure everything up front. A small site can start with just a title and a content root:

From there, you can add:

Here is a typical starting configuration for a documentation site:

These are the main fields you are most likely to use in [site].

Use domain to set the custom domain for your published site.

This should be a normal hostname. The canonical source of truth is Stencila Cloud, so this value is best understood as the workspace's local configuration.

Use title for the human-readable name of your site.

This is used by the title layout component and as fallback metadata.

You can set author as either a simple string or a richer author object.

or:

This is useful for metadata and for components such as copyright.

For simple cases, logo can just be an image path:

If you need responsive or dark-mode variants, use a table instead:

Available fields include default, mobile, tablet, dark, dark-mobile, dark-tablet, link, and alt.

You do not need to define every variant. Stencila falls back sensibly when a more specific logo is missing. For example, a dark mobile logo falls back through dark, then mobile, then default.

These fields help shape the labels and presentation of your navigation without requiring you to manually define every navigation item.

Assigns icons to navigation items.

Lookup order is:

Icons can be written as "banana" for the default Lucide set or "lucide:banana" for an explicit library prefix.

Overrides the label shown for navigation items.

Use this when automatic title-casing is not what you want.

Adds short descriptions for navigation items, mainly used by components such as nav-menu.

Adds social and external links, usually shown with the social-links layout component.

Supported shortcuts include:

If both x and twitter are provided, x takes precedence.

Adds featured or promotional content to a nav menu dropdown.

This is keyed by the dropdown's parent group, using the same matching rules as icons and descriptions. The title field is required. Other supported fields include badge, icon, image, description, and cta.

If both icon and image are provided, the icon takes precedence.

If you do not define nav, Stencila can derive navigation automatically from your routes and content tree. Define nav when you want explicit ordering, grouping, or labels.

There are three main item forms:

Useful fields on nav items include:

All routes must be internal and start with /.

root sets the directory that should be treated as the source for the site.

This changes how routes are calculated. For example, if root = "docs", then docs/guide.md becomes /guide/ rather than /docs/guide/.

Use exclude for file globs that should not be published.

Patterns are relative to root if it is set, otherwise the workspace root.

Use formats when you want extra generated output formats.

The exact formats available depend on the surrounding publishing pipeline, so this is usually an advanced setting.

Controls access levels for routes.

Access levels are ordered:

public < subscriber < password < team

Route keys must start and end with /, and the longest matching prefix wins. Access rules are cumulative, so child routes should not be less restrictive than their parents.

Lets you map routes explicitly to files, redirects, or spread configurations.

Common uses include:

Redirect status codes include 301, 302, 303, 307, and 308. Spread modes are grid for cartesian products and zip for positional pairing. Advanced spread routes can also use reserved placeholders such as {tag}, {branch}, and {i}.

The layout system controls where site-level UI appears around your content. In most cases, the easiest approach is to start from a preset and customize only what you need.

If you do not choose a preset explicitly, the layout behaves like the docs preset.

In practice, these presets differ mainly in which built-in components are placed in which regions. For example, docs includes left navigation, breadcrumbs, prev/next links, and a right-side table of contents, while blog removes the left sidebar and bottom navigation. The landing preset removes sidebars and also sets main.width = "none", main.padding = "none", and main.title = false.

You can place components into six layout regions:

Each region has start, middle, and end slots. Horizontal regions can also use rows for multi-row layouts. Sidebars use only start, middle, and end.

A region can be omitted to inherit its current behavior, configured as a table, or set to false to disable it.

Common built-in components include:

The generated component reference also documents edit-on as a configurable component type.

Use [site.layout.main] to control content width, padding, and title display.

Use overrides when different parts of your site need different layouts.

The first matching override wins, so order matters.

Within an override, explicit settings replace the preset or base layout, while omitted regions inherit from it. Use false to disable a region explicitly.

You can define reusable named components under [site.layout.components].

If the component name matches a built-in component type, type can be omitted. When you reference a component by name in a region, it must either be a built-in component type or a name you defined under [site.layout.components].

Use [site.layout.responsive] to control when sidebars collapse and how their toggle controls work.

Supported toggle styles are fixed-edge, header, and hamburger.

Glide enables faster client-side navigation between internal pages.

When enabled, Stencila can preload likely next pages and use smoother page transitions where the browser supports them.

Search builds a client-side full-text index during site rendering.

When include-types is not specified, the generated docs describe the default set as:

Heading, Paragraph, Datatable, CodeChunk, Figure, and Table

Use search when your site is large enough that readers need quick lookup across pages.

Sitemap generation writes machine-readable route lists for search engines, validators, and other tools that need to discover published pages.

The simple boolean form enables sitemap generation with the default format of xml.

Use the detailed form when you want to control:

In practice:

Use sitemaps when you want external crawlers or downstream tooling to discover your published routes more reliably.

These features are especially useful for team documentation, data publishing, and collaborative knowledge bases. Several of them require workspace.id because enforcement happens through Stencila Cloud.

In practice, you will usually want workspace.id configured before using reviews, uploads, remotes, restricted access, or custom domain management.

Enables page comments and suggestions.

You can limit where reviews appear with include and exclude, and you can control whether they are available on spread routes with spread-routes.

Enables file uploads through GitHub pull requests.

This is useful for workflows where contributors need to submit datasets or other files without writing directly to the repository.

Enables adding Google Docs or Microsoft 365 documents via GitHub PRs.

This is useful when teams author in cloud editors but want the site backed by a repository.

Controls the floating action button zone used by reviews, uploads, and remotes.

position can be bottom-right, bottom-left, top-right, or top-left. direction can be vertical or horizontal. mode can be collapsed or expanded.

When enabled, Stencila can generate index pages for directories that do not already have their own content file.

This is especially useful for documentation trees where some folders exist only to organize child pages.

The specimen page is a preview surface for site components and styles. It has its own layout configuration.

The specimen layout uses the same layout system as [site.layout].

If you are building a typical docs site, a good progression is: