Output and export settings

Configure metadata providers, application exports, Markdown headers, and discovery indexes. These keys belong in docs.config.yaml or an included configuration file. For file composition and validation commands, see Configure your project. Use the configuration index to find another setting.

metadata

metadata.provider.module names an optional local module that exports provideMetadata(context). The module can supply owned page fields to the build. The framework does not run an external vocabulary validator or publish supplied fields automatically. See custom metadata for the return shape and ownership rule.

metadata:
  provider:
    module: ./metadata/provider.mjs

The path is relative to the config file that declares it. provider accepts only module.

exports

Optional named targets for shoalrun export. They select portable application content independently of website navigation and site.contentFilter. The normal website build does not emit export bundles automatically. See export content into an application.

Each target accepts these fields:

exports:
  app-help:
    formats: [markdown, html]
    documents: [guide.api-keys, guide.billing]
    publicBase: /help/

The export preserves whole-page content, including all reader sections. It flattens interactive components into readable static content and omits website/browser runtimes. Unsupported output, escaping assets, and unavailable document fallbacks fail. exports and its target fields are validated for unknown keys.

outputs

Use outputs to configure the HTML, Markdown, discovery, and text artifacts produced by a build.

The build always writes /llms.txt, documents.json, redirects.json, and resource-headers.json; there are no settings for them.

A short Markdown header on every page:

outputs:
  markdown:
    metadata:
      format: yaml-frontmatter
      fields:
        id: frontmatter.id
        title: frontmatter.title
        summary: frontmatter.summary
        description: frontmatter.description
        canonical: publication.canonicalUrl

Add fields for one page type, and define a profile pages can select with markdownMetadata: versioned:

outputs:
  markdown:
    metadata:
      format: yaml-frontmatter
      fields: { id: frontmatter.id, title: frontmatter.title }
      byType:
        api-reference:
          addFields: { operations: frontmatter.operations }
      profiles:
        versioned:
          addFields: { version: publication.version, language: publication.language }

Use another Shiki theme, and turn off search:

outputs:
  html:
    highlighting: { provider: shiki, theme: github-light }
    search: { provider: none }

Plug in your own search and highlighter modules:

outputs:
  html:
    highlighting: { provider: custom, module: ./highlight.mjs }
    search: { provider: custom, module: ./search/hosted.js }

Agent discovery index

Every published page is included automatically, using its title and frontmatter summary. You do not need to list page IDs. Omit outputs.llms for automatic grouping, or choose a bare alphabetical list of links and summaries:

outputs:
  llms:
    format: flat

format accepts grouped (the default) or flat. Flat mode includes all pages under Pages, without optional groups or repeated type labels. Discovery resources and API contracts remain linked, and fictional labels still apply. Grouping overrides are optional; primaryIds is an exception list, not an inventory.

outputs.llms controls grouping in /llms.txt. The build groups primary pages by type, puts secondary pages under ## Optional, and lists /search-index.json under Discovery only when that file is generated. The complete manifest remains available for inventory. fictionalPrefixes also sets demo: true on matching pages in documents.json, search-index.json, and search-index.min.json. Matching uses the authored slug, including descendants, independently of publication or site path prefixes. Other pages receive demo: false, meaning unmarked rather than verified as a live service.

outputs:
  llms:
    primaryIds: [guide.components]
    optionalTypes: [recipe, ingredient, cookbook]
    optionalPrefixes: [/author/components]
    fictionalPrefixes: [/example-api]

primaryIds keeps named document IDs in their primary type section even when an optional type or prefix matches; fictional examples remain optional. Entries sort alphabetically within each section or optional group. Type labels appear only in the mixed optional groups. optionalTypes defaults to recipe, ingredient, and cookbook. Both prefix lists default to empty. Prefixes match page slugs before publication and base-path prefixes, on path boundaries. Fictional entries are always optional, labeled in the index, and carry a disclaimer in their Markdown twins. Use fictional prefixes only for synthetic examples, not real product API references.

Related reading

Read first

• Organize project configuration — Learn how files combine and how to validate configuration changes.

Reference while working

• Configuration reference — Find configuration settings in another topic.