Overview

When used standalone, these inputs come from the user or the agent's prompt. When used within a workflow, the workflow's stage prompt will specify how to obtain them.

Outputs

Core rules

• Always inspect the existing stencila.toml before making changes.
• Preserve existing comments, formatting, and unrelated sections when editing.
• Use edit_file for targeted TOML edits rather than rewriting the entire file.
• Generate valid TOML — quote keys containing special characters, use correct array and table syntax.
• Validate configuration after changes with stencila config check.
• Use snap for visual verification of layout, navigation, and component changes when a server is running.
• Do not invent asset files (logos, images); ask the user for paths or use clearly marked placeholders.
• When a field supports both simple and detailed forms (search, reviews, uploads, remotes, auto-index), use the simple form when defaults suffice.

Steps

1. Inspect the current state.

   • Read the existing stencila.toml (typically at the workspace root).
   • Note which [site] fields already exist and their current values.
   • Identify what the user wants to add or change.

2. Determine the scope of changes.

   • Identify which subsections are affected (top-level fields, nav, layout, routes, etc.).
   • If the request is ambiguous (e.g., "set up my site"), ask the user what they need before generating configuration.
   • Use references/site-configuration.md to look up correct field names, types, and value formats.

3. Generate or update the TOML configuration.

   • For new subsections, add them in a logical order within the file.
   • For existing subsections, edit only the affected fields.
   • Use the correct TOML syntax for each field type:
     • Simple strings: title = "My Site"
     • Arrays: exclude = ["**/*.draft.md", "temp/**"]
     • Tables: [site.layout] with fields below
     • Inline tables: cta = { label = "Start", route = "/docs/" }
     • Array of tables: [[site.layout.overrides]]

4. Validate the configuration.

   • Run stencila config check to validate the configuration and catch schema or value errors.
   • Then run stencila config show to inspect the resolved configuration and verify the final effective values.
   • Check for validation errors (invalid domain, unknown component names, invalid route patterns).

5. Visually verify layout and component changes (when applicable).

   • If the change affects layout, navigation, or visual components and a Stencila server is running, use snap to verify.
   • Prefer rendered directory routes for index-like source files: index.*, main.*, and README.* act as the index.html for their containing directory, so docs/README.md, docs/main.md, and docs/index.md all render at "/docs/".
   • See references/snap-tool.md for the typical verification workflow.
   • If snap is unavailable, mark visual verification as pending and recommend specific commands.

Subsection guidance

Use this section for quick patterns and common examples. For complete field details, defaults, and additional forms, check references/site-configuration.md.

Domain, title, author, logo

These are top-level [site] fields. Set them directly:

[site]
domain = "docs.example.org"
title = "My Documentation"
author = "Acme Inc"
logo = "logo.svg"

For responsive logos, use the table form:

[site.logo]
default = "logo.svg"
dark = "logo-dark.svg"
mobile = "logo-mobile.svg"
alt = "Acme Documentation"

Navigation

If not specified, navigation is auto-generated from document routes. For custom ordering:

[site]
nav = [
  "/",
  { label = "Docs", children = [
    "/docs/getting-started/",
    "/docs/configuration/",
  ]},
  "/about/",
]

Use [site.icons], [site.labels], and [site.descriptions] to customize nav appearance without restructuring.

Layout

Start with a preset, then override specific regions:

[site.layout]
preset = "docs"

[site.layout.header]
end = ["site-search", "color-mode"]

[[site.layout.overrides]]
routes = ["/"]
preset = "landing"

Available presets: docs, blog, landing, api. Built-in components: logo, title, breadcrumbs, nav-tree, nav-menu, nav-groups, toc-tree, prev-next, color-mode, copyright, edit-source, edit-on:gdocs, edit-on:m365, copy-markdown, site-search, site-review, social-links.

Routes

Use [site.routes] to map routes to files, add redirects, or generate route variants from arguments.

[site.routes]
"/" = "index.md"
"/old-docs/" = { redirect = "/docs/", status = 301 }
"/{region}/report/" = { file = "reports/regional.smd", arguments = { region = ["americas", "emea"] } }

Access control

Use [site.access] to control who can view specific routes, with a default access level and per-route overrides.

[site.access]
default = "public"
"/internal/" = "team"
"/data/" = "password"

Route keys must start and end with /.

Interactive features (reviews, uploads, remotes)

These require workspace.id to be set. Use simple boolean form when defaults suffice:

[site]
reviews = true
uploads = true
remotes = true

Use detailed form for fine-grained control. Position is configured via [site.actions].

Examples

Input: Set up a basic site configuration for a documentation project.

Output:

[site]
title = "Project Documentation"
author = "Project Team"
search = true

[site.layout]
preset = "docs"

Input: Add GitHub and Discord social links to our site.

Output: Edit the existing stencila.toml to add:

[site.socials]
github = "org/repo"
discord = "invite-code"

Input: Add search to an existing docs site while preserving comments and unrelated settings.

Before:

[workspace]
id = "acme-docs"

[site]
title = "Acme Docs"

[site.layout]
preset = "docs"

After:

[workspace]
id = "acme-docs"

[site]
title = "Acme Docs"
search = true

[site.layout]
preset = "docs"

Input: Configure a landing page for the root with docs layout for everything under /docs/.

Output:

[site.layout]
preset = "landing"

[[site.layout.overrides]]
routes = ["/docs/**"]
preset = "docs"

Input: Add a redirect from /old-path/ to /new-path/ with a 301 status.

Output: Add to [site.routes]:

"/old-path/" = { redirect = "/new-path/", status = 301 }

Input: Set up access control so internal docs require team membership but everything else is public.

Output:

[site.access]
default = "public"
"/internal/" = "team"

Input: Enable reviews with custom settings — public but require GitHub auth, only on docs pages.

Output:

[site.reviews]
enabled = true
public = true
anon = false
include = ["docs/**"]

Input: Configure the header to show logo, nav menu, search, and color mode toggle.

Output:

[site.layout.header]
start = "logo"
middle = "nav-menu"
end = ["site-search", "color-mode"]

Edge Cases

• If stencila.toml does not exist, create it with the necessary sections. Include [workspace] if needed for features requiring workspace.id.
• If the user asks for reviews, uploads, or remotes but workspace.id is not set, warn that these features require it and ask whether to add a placeholder.
• If the user provides a domain that does not match the validation regex, suggest a corrected format.
• If layout component names are misspelled or unknown, suggest the correct built-in component name from the known list.
• If the user wants both a landing page root and docs layout for subpages, use layout overrides — do not try to set two presets at the top level.
• If nav routes do not start with /, warn that only internal routes are supported in site navigation.
• If access route keys do not end with /, add the trailing slash and explain the requirement.
• If site.root is set, remind the user that routes and file paths are relative to that directory.
• If snap is unavailable, mark visual verification as pending, rely on stencila config check for validation and stencila config show for inspection, and recommend specific snap commands.
• If the user wants to remove a subsection entirely, delete the relevant TOML lines rather than setting empty values.
• When editing inline tables or arrays of tables, be careful with TOML syntax — inline tables must be on one line, array-of-tables uses [[double brackets]].