A section is a heading and the content beneath it. For content delivery, Shoalrun selects sections beginning at a top-level ## heading, including nested subsections, and ending before the next ## or # heading. Exporting a section extracts that part of the page so an application can use it separately.
Available since 0.1.0-alpha.13.
Why a section needs a declaration
A section can lose essential information when separated from its page. For example:
Before resetting your database, back it up. Resetting deletes all records.
## Reset the database
Run the reset command from Settings.
Exporting only “Reset the database” would leave out the backup instruction and deletion warning. Before exporting this section, move those details into the section or export the whole page instead.
A standalone section is one the author has reviewed and declared understandable without the rest of the page. Record that judgment in the page's standaloneSections frontmatter. This is what “approval” means here: a declaration in a source file, not a separate reviewer, permission request, or approval service. Shoalrun checks that the declaration exists and identifies a section; it cannot prove the content is complete.
You need this declaration when exporting an individual section. You do not need it to write a page, link to a heading, or export a whole page. Declaring a section does not export it: the export target separately chooses which declared sections to include.
Identify the section
A section reference contains a document ID and a section ID. Ordinary top-level ## headings receive derived IDs. Use an explicit marker when an application must retain the same reference after a heading changes.
Derive an ID
## Request a refund
This heading derives request-a-refund. Derivation normalizes the heading text, uses lowercase letters, numbers, and dashes, and adds a suffix for repeated headings. Changing a heading or reordering repeated headings can change a derived ID. Compare exports before publishing such edits.
Preserve an explicit ID
## Request a refund <Anchor id="refunds" />
The ID remains refunds if the title changes. The marker must be the single trailing element of a root H2, with one literal id and no children. IDs use 1–512 lowercase letters, numbers, or dashes, beginning with a letter or number. Duplicate IDs and collisions with another anchor fail. Anchor is a reserved built-in name.
The marker cannot be placed inside emphasis, a link, a tab, a reader section, or a snippet. Code examples containing marker syntax remain ordinary code. Both ## headings and Setext H2 headings are supported.
Declare a section ready for separate use
Read the section without the rest of the page. Check that it includes the prerequisites, definitions, warnings, and steps needed for its stated purpose. Then add its ID to the page's frontmatter:
standaloneSections:
- { id: refunds, context: section }
context: section records that your review covered the section on its own, without the page introduction. A derived ID can be declared too; an explicit <Anchor> is optional. Next, select the section in an export target using resources. If the declaration is missing, section export fails.
Recheck the declaration when the section or its prerequisites change. If the content needs the rest of the page to make sense, export the whole page instead.
Compatibility with heading-title declarations
Existing projects may use the older title-string form:
standaloneSections:
- Request a refund
This form remains supported. It matches the exact heading text and approves a discovery read that includes page introduction and reading-path context. It does not approve a section-only export. Keep it when the section relies on that surrounding context.
Do not mechanically replace a title string with { id, context: section }. First review the section without the page introduction and include any missing prerequisites, definitions, or warnings. Then replace the title string with the ID-based object and select the section in the export target. A heading cannot be declared in both forms.
The object form also marks the section as approved for contextual discovery when it meets discovery size requirements. Switching to the object does not remove context from existing discovery responses; it additionally approves the section-only export. See section discovery for those response rules.
Maintain references
Renaming an explicit ID or removing an exported section removes a public content reference. Use --previous-manifest and --fail-on-removed when publishing an established collection. An unchanged ID with edited content receives a new digest; identity does not mean immutable wording.
HTML, Markdown, and agents
HTML preserves the existing heading-derived anchor and adds an explicit ID as an alias when it is distinct and available. Markdown keeps the clean heading text. Agents receive IDs through outlines or export metadata; they should follow the returned resource URL rather than invent a Markdown fragment URL. Existing contextual MCP section reads retain their page context and size heuristics; application fragments are a separate output.