Skip to content

feat: support multiple guides declared in _readme.yaml - #69

Open
gkoberger wants to merge 2 commits into
mainfrom
feat/multi-guides
Open

gkoberger wants to merge 2 commits into
mainfrom
feat/multi-guides

Conversation

@gkoberger

Copy link
Copy Markdown
Contributor

What

Multiple guides is shipping soon: a project can declare extra sections (a second guide, a second API reference) in a _readme.yaml file at the repo root. Until now the CLI only knew the built-in directories, so anything in a declared section was invisible to it.

navigation:
  - kind: guide
    directory: docs
  - kind: guide
    directory: sdks
    name: SDKs
  - kind: reference
    directory: partner-api
    name: Partner API

The CLI now reads this file and treats each declared section like the built-in one of its kind.

The file is optional. A repo without one resolves to the built-in sections and behaves exactly as it did before, with no new warnings.

Changes

  • lint: a declared guide gets the same checks as docs/, a declared reference the same as reference/ (frontmatter, ordering, duplicates, nesting, links, components, content). doc: links resolve across all sections.
  • oas:sync / oas:validate / OAS lint rules: cover specs in every reference section, not just reference/. Results gain a section field; existing fields are unchanged. oas:sync checks every section for symlinks before it writes to any of them.
  • New config lint rule: validates _readme.yaml itself, using the same rules gitto applies (directory naming, reserved names, built-ins locked to their kind, duplicates, one home/version/etc.). It also warns when a top-level folder has an _order.yaml but nothing declares it, since ReadMe will ignore that folder.
  • dev: the nav uses the declared sections, with the names and order from the file.
  • Bootstrap: the "is this a ReadMe repo" check accepts a declared section in place of docs/ or reference/.
  • A symlinked _readme.yaml is refused, in line with the other symlink protections.
  • README and the readme-cli skill document the file. dist-gha is rebuilt.

One deliberate difference from gitto

gitto ignores the whole file (and falls back to the built-ins) when it holds a property or kind it doesn't recognize. The CLI reports those as warnings, not errors, so that a format addition on the server doesn't fail CI for everyone on an older CLI. The warning says what ReadMe will do. Easy to flip to errors if we'd rather match exactly.

Testing

  • 319 tests pass, including 17 new ones in test/sections.test.js; npm run lint is clean.
  • Compared the config rule against gitto 9.14.0's real fromYAML + validateConfig on 45 config files: same verdict on 41, and the other 4 are the warn-instead-of-error cases above (plus a non-list navigation, which gitto reads as empty and the CLI warns about).
  • Ran lint, oas:sync, oas:validate and the bundled Action against a sample repo with a second guide and a second reference, and against a repo with no _readme.yaml.
  • Ran dev from a packed-and-installed build of an earlier revision of this branch (before rebasing onto 0.5.0) and confirmed the nav, sidebars, pages and OAS previews for declared sections. Not re-run after the rebase.

Not covered

  • The site rejects a section directory that collides with one of the project's languages or versions (v2, de). The CLI can't see those settings, so it doesn't check.
  • The CLI can't tell whether a project has multiple guides enabled; it trusts _readme.yaml whenever it is present.
  • import still writes only to docs/ and reference/.

Projects with multiple guides declare extra sections (a second guide, a
second API reference) in a _readme.yaml at the repo root. The CLI now reads
that file and treats each declared section like the built-in one of its
kind, across lint, oas:sync, oas:validate and the dev server.

The file is optional: a repo without one resolves to the built-in sections
and behaves exactly as before.

lint also gains a config rule that validates _readme.yaml with the same
rules ReadMe applies, and warns about a folder that is laid out like a
section but is not declared.
@greptile-apps

greptile-apps Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 4/5

[Medium impact] The changes affect several CLI workflows, but only when projects use declared sections.

The PR appears safe to merge, with a non-blocking false lint error for sections named constructor.

Findings

  1. P2 Valid section fails lint ▶

Reviews (1) · Last reviewed commit: "feat: support multiple guides declared i..." · Reviewed by Greptile

Comment thread src/validators/config.js Outdated
return;
}

const builtInKind = BUILT_IN_KINDS[directory];

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Valid section fails lint

A declared section named constructor makes lint fail even though the name meets the directory rules. BUILT_IN_KINDS[directory] reads the inherited Object constructor, so the validator treats this directory as a built-in and reports an impossible required kind.

Check isBuiltInDirectory(directory) before reading the kind, as the section loader already does.

Suggested change
const builtInKind = BUILT_IN_KINDS[directory];
const builtInKind = isBuiltInDirectory(directory) ? BUILT_IN_KINDS[directory] : undefined;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 7040072: the lookup now goes through isBuiltInDirectory, and the same bare lookup in the lint summary's section labels is fixed too. Added a test for a section named constructor.

A declared section named `constructor` is a valid directory, but a bare
lookup on the built-in kinds table found Object.prototype.constructor and
reported it as a built-in with an impossible kind. The lint summary had the
same lookup for its section labels.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant