Repository navigation
Conversation
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.
[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 Findings
Reviews (1) · Last reviewed commit: "feat: support multiple guides declared i..." · Reviewed by Greptile |
| return; | ||
| } | ||
|
|
||
| const builtInKind = BUILT_IN_KINDS[directory]; |
There was a problem hiding this comment.
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.
| const builtInKind = BUILT_IN_KINDS[directory]; | |
| const builtInKind = isBuiltInDirectory(directory) ? BUILT_IN_KINDS[directory] : undefined; |
There was a problem hiding this comment.
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.
What
Multiple guides is shipping soon: a project can declare extra sections (a second guide, a second API reference) in a
_readme.yamlfile at the repo root. Until now the CLI only knew the built-in directories, so anything in a declared section was invisible to it.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 asdocs/, a declared reference the same asreference/(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 justreference/. Results gain asectionfield; existing fields are unchanged.oas:syncchecks every section for symlinks before it writes to any of them.configlint rule: validates_readme.yamlitself, using the same rules gitto applies (directory naming, reserved names, built-ins locked to their kind, duplicates, onehome/version/etc.). It also warns when a top-level folder has an_order.yamlbut nothing declares it, since ReadMe will ignore that folder.dev: the nav uses the declared sections, with the names and order from the file.docs/orreference/._readme.yamlis refused, in line with the other symlink protections.readme-cliskill document the file.dist-ghais 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
test/sections.test.js;npm run lintis clean.configrule against gitto 9.14.0's realfromYAML+validateConfigon 45 config files: same verdict on 41, and the other 4 are the warn-instead-of-error cases above (plus a non-listnavigation, which gitto reads as empty and the CLI warns about).lint,oas:sync,oas:validateand the bundled Action against a sample repo with a second guide and a second reference, and against a repo with no_readme.yaml.devfrom 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
v2,de). The CLI can't see those settings, so it doesn't check._readme.yamlwhenever it is present.importstill writes only todocs/andreference/.