Pick up markdown at the root of a docs source

[NullVoxPopuli]

A .md file sitting directly in a docs() source was silently dropped. Only markdown inside a folder became a page. Now a root-level file is a page of the group itself, in the nav next to the folders.

docs/
  intro.md        -> /GroupName/intro.md     (was: warned about, then skipped)
  guides/
    advanced.md   -> /GroupName/guides/advanced.md

Same for the co-located pages: src/templates/welcome.md is served at /welcome.md.

What changed

src/build/plugins/markdown-pages/parse.js:

• build() puts a page with no folder segments at the root of the tree, instead of console.warn + continue
• gather() no longer skips root-level markdown, or a root-level nav-only link entry (a json with an href and no page of its own). A root meta.json is still the source's own config, not a page
• a leading ./ no longer turns into a folder named .

A root-level page's groupName is ''. There is no folder to name it after, and the source's display name lives in the docs() config, a layer above build(). Documented on Page in src/types.ts. Nothing reads it for layout: search entries get the group's display name from setup.js, and docsManager derives a page's group from its path.

Consequences worth knowing

• Root-level pages take part in the source's meta.json order alongside the folder names. A source that already has an order and a stray root-level README.md will now fail the build until that file is listed (or moved out of the source).
• A root-level index.md becomes the group's first page and, like a folder's index.md, gets no separate <PageNav /> link. The group's own <GroupNav /> link points at it.
• The existing "a page cannot share a name with a sibling folder" check applies at the root too.

Tests

• parse.build.test.ts: root-level page, mixed with folders, .gjs.md, per-page config, leading ./, and the name-collides-with-a-folder error
• parse.rootPages.test.ts (new): through parse() and sortTree(), so it covers gathering, sorting, a root meta.json order that includes a root-level page, a root-level href link entry, and app/src/templates paths
• all five test apps pass in Chrome. The three that already had an empty, silently skipped docs/top.md now have content in it, so it is a real page and (by the existing sort rules) each group's first page. The index-redirect and all-links expectations move with it.
• docs-app builds

Docs: a "Pages at the root of a source" section in docs() configuration, and a note in Ordering.

🤖 Generated with Claude Code

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
kolay-docs-app	Ready	Preview	Aug 19, 2026 3:47pm