Add frontmatter and sidebar ordering to docs/ for the new docs site - #558
Merged
Conversation
The new Automators docs site (docs.automators.com, see
automators-com/docs) renders each product's docs/ folder with Fumadocs,
which requires title (and reads description) from YAML frontmatter, and
uses a meta.json for sidebar ordering. Neither existed here yet, so the
site's build failed outright on every one of these 17 files
("title: Invalid input: expected string, received undefined").
- Added `title`/`description` frontmatter to every docs/*.md file, and
removed each file's leading `# Heading` line since the site renders
the title separately (DocsTitle) — left in place it would have shown
twice.
- Added docs/meta.json ordering pages by what a first-time reader needs:
getting-started, authoring, recording, self-help, agent-testing,
capture, multi-surface first, then the rest.
Not touched: docs/loop/ (corpus.yaml, ledger.yaml,
milestones/m2-falsifiability.md) looks like internal planning content
rather than documentation, and now that files need frontmatter to
publish, it's excluded from the site by the same rule rather than a
special case — flagging here in case docs/loop/ should move out of
docs/ entirely so it doesn't sit inside what's now a public-facing
folder.
authoring.md (1682 lines), getting-started.md (1426 lines), and agent-testing.md (1185 lines) were each a single page covering many subtopics — on the new docs site that meant one very long page per sidebar entry, with the reader scrolling past unrelated sections to find the next topic. Inspired by loopedautomation/agent-framework's docs/ structure (many short, single-topic files plus "---Section---" separators in meta.json for sidebar grouping, rather than deep folder nesting): - authoring.md -> authoring/ (13 pages: index, actions, assertions, variables-and-exports, iframes-and-cookies, repeating, desktop-apps, multi-surface-flows, out-of-band-assertions, visual-and-network, agent-steps, security-controls, troubleshooting) - getting-started.md -> getting-started/ (13 pages, one per surface/ concern: record-and-replay, python-api, live-app-tests, web-flows, test-context-seeding, sap-flows, vision-flows, api-flows, agent-flows, resilience, secrets-and-config, roadmap) - agent-testing.md -> agent-testing/ (8 pages: index, concept, spec-shape, running-agent-flows, phasing, security, review-notes, status-and-scope) Each new page keeps title/description frontmatter split from the original file's headings, and each folder gets its own meta.json for page order. Root docs/meta.json now groups the top-level pages under ---Introduction---, ---Testing agents---, ---Guides---, ---Reference---, and ---Behind the scenes--- headers. Verified against the docs site locally: next build succeeds (152 pages, up from the previous flat structure), and the reorganized sidebar/pages render correctly in a browser. Known follow-up (next commit): some internal links still point at anchors in the old mega-pages (e.g. multi-surface.md linking to authoring.md#multi-surface-flows-apps-and-in-blocks, now authoring/multi-surface-flows.md) and need updating to the new paths.
The previous commit split authoring.md, getting-started.md, and agent-testing.md into per-topic folders, but left cross-references elsewhere pointing at the old single-file paths and anchors (e.g. multi-surface.md linking to authoring.md#multi-surface-flows-apps-and-in-blocks, which is now authoring/multi-surface-flows.md). Rewrote every [text](old-file.md#anchor) link across docs/ to its new location, adjusting the relative path prefix for files that moved folder depth (e.g. a link from authoring/desktop-apps.md to getting-started.md now needs ../getting-started/...). Verified against the docs site: next build succeeds, and the compiled HTML resolves the fixed links to their correct new routes (checked multi-surface.md's link to authoring/multi-surface-flows and authoring/desktop-apps.md's link to getting-started/live-app-tests#deploying-a-uwp-app-on-a-ci-runner).
6 tasks
HappyDevs1
added a commit
that referenced
this pull request
Sep 8, 2026
Merging #558 (which split docs/authoring.md and docs/getting-started.md into per-topic folders) broke CI on main: three tests still referenced the old single-file paths, two of them via include_str!, which fails to compile rather than fail at runtime. - rules::no_documented_example_shows_a_shape_the_grammar_refuses (flowproof-agent): its PAGES list named docs/authoring.md and docs/getting-started.md directly via include_str!. Expanded it to list every file under docs/authoring/ and docs/getting-started/ individually — a strict improvement, since a failure now names the specific split file rather than a huge merged one. - the_quickstart_quotes_the_shipped_agent_example_verbatim (flowproof-cli): also used include_str! on docs/getting-started.md to verify the README and docs both quote the same shipped example verbatim. The quoted section moved to docs/getting-started/record-and-replay.md; updated the path. - every_visible_cli_flag_is_mentioned_in_the_docs / every_visible_subcommand_is_mentioned_in_the_docs (flowproof-cli/documented_flags.rs): built its corpus with a non-recursive `read_dir(docs/)`, so it silently stopped seeing anything under the new docs/authoring/ and docs/getting-started/ folders. 15 real flags (record --vars, run --strict, doctor --prompt, etc. — all still documented, just no longer in a page this test could see) started failing as "undocumented". Made the corpus builder recurse into subfolders. Verified locally, not just by reasoning about it: `cargo clippy --workspace --all-targets --all-features -- -D warnings` (CI's exact command) is clean, and `cargo test --workspace --all-features` passes except for doctor_ai_e2e, which fails in this sandbox because of ambient AI credentials in the local environment (asserts "no key -> model call fails" but a real call succeeds here) — unrelated to docs/ and confirmed not touching any docs path.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
title/descriptionYAML frontmatter to every file indocs/, required by the new Automators docs site (Fumadocs-based, seeautomators-com/docs) — without it,next buildthere fails outright.# Headingline since the site renders the title separately; left in, it would show twice on every page.loopedautomation/agent-framework's docs structure (many short single-topic files +"---Section---"separators inmeta.jsonfor sidebar grouping):authoring.md(1682 lines) →authoring/(13 pages)getting-started.md(1426 lines) →getting-started/(13 pages)agent-testing.md(1185 lines) →agent-testing/(8 pages)meta.jsonto each new folder and reorganizes the rootdocs/meta.jsonwith---Introduction---,---Testing agents---,---Guides---,---Reference---,---Behind the scenes---section headers.multi-surface.md→authoring.md#multi-surface-flows-apps-and-in-blocksis nowauthoring/multi-surface-flows.md), adjusting relative path depth where a link now crosses folders.Not touched — needs a decision
docs/loop/(corpus.yaml,ledger.yaml,milestones/m2-falsifiability.md) looks like internal planning content, not documentation. It has no frontmatter, so it's excluded from the site by the same rule as any other file missing atitle— but flagging that it may be worth movingdocs/loop/out ofdocs/entirely, since that folder is now effectively public-facing.Test plan
next buildsucceeds, 152 pages generated (up from the previous flat structure)docs/loop/milestones/m2-falsifiability.mdcorrectly does not publish (404s)meta.json, no duplicate heading, no leaked frontmatterdocs/loop/disposition