From 30892a72381ba575c589377112f0ee8a14f27b39 Mon Sep 17 00:00:00 2001 From: Rishabh Date: Thu, 14 May 2026 10:12:01 +0530 Subject: [PATCH 1/3] fix: meta.json order sorting for folders without index pages Derive folder path from first child page URL instead of relying on node.index which is absent for folders without an index file. Co-Authored-By: Claude Opus 4.6 (1M context) --- packages/chronicle/src/lib/source.ts | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/packages/chronicle/src/lib/source.ts b/packages/chronicle/src/lib/source.ts index f7e4db1..3e65ba5 100644 --- a/packages/chronicle/src/lib/source.ts +++ b/packages/chronicle/src/lib/source.ts @@ -120,14 +120,31 @@ export function invalidate() { cachedNavMap = null; } +function getFolderPath(node: Folder): string | null { + const firstPage = findFirstPage(node); + if (!firstPage) return null; + const parts = firstPage.url.split('/').filter(Boolean); + parts.pop(); + return '/' + parts.join('/'); +} + +function findFirstPage(node: Folder): { url: string } | null { + for (const child of node.children) { + if (child.type === 'page') return child; + if (child.type === 'folder') { + const found = findFirstPage(child); + if (found) return found; + } + } + return node.index ?? null; +} + function getOrder(node: Node, pageOrderMap: Map, folderOrderMap: Map): number | undefined { if (node.type === 'page') return pageOrderMap.get(node.url); if (node.type === 'folder') { - if (node.index) { - const fromMeta = folderOrderMap.get(node.index.url); - if (fromMeta !== undefined) return fromMeta; - return pageOrderMap.get(node.index.url); - } + const folderPath = getFolderPath(node); + if (folderPath && folderOrderMap.has(folderPath)) return folderOrderMap.get(folderPath); + if (node.index) return pageOrderMap.get(node.index.url); } return undefined; } From 988e7afa9ae9377934021bc6fdc8e73fcb3f6514 Mon Sep 17 00:00:00 2001 From: Rishabh Date: Thu, 14 May 2026 10:13:15 +0530 Subject: [PATCH 2/3] docs: add sorting section for pages and folders Explains how to sort pages via frontmatter order and meta.json pages array, and how to sort folders via meta.json order. Co-Authored-By: Claude Opus 4.6 (1M context) --- examples/basic/content/docs/features.mdx | 66 ++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/examples/basic/content/docs/features.mdx b/examples/basic/content/docs/features.mdx index 72bde9c..8bbfdf9 100644 --- a/examples/basic/content/docs/features.mdx +++ b/examples/basic/content/docs/features.mdx @@ -128,6 +128,72 @@ lastModified: 2024-01-15 --- +## Sorting Pages and Folders + +Control the order of pages and folders in the sidebar. + +### Sorting Pages + +Add `order` to page frontmatter. Lower numbers appear first. Pages without `order` appear at the end. + +```mdx +--- +title: Introduction +order: 1 +--- +``` + +```mdx +--- +title: Installation +order: 2 +--- +``` + +Alternatively, use the `pages` array in `meta.json` to explicitly order pages within a folder: + +```json +{ + "pages": ["introduction", "installation", "configuration"] +} +``` + +### Sorting Folders + +Add `order` to the folder's `meta.json`. This works even for folders without an index page. + +``` +docs/ +├── getting-started/ +│ └── meta.json ← {"title": "Getting Started", "order": 1} +├── guides/ +│ └── meta.json ← {"title": "Guides", "order": 2} +└── api/ + └── meta.json ← {"title": "API Reference", "order": 3} +``` + +`getting-started/meta.json`: +```json +{ + "title": "Getting Started", + "order": 1 +} +``` + +`guides/meta.json`: +```json +{ + "title": "Guides", + "order": 2 +} +``` + +Folders without `order` appear after all ordered folders. + +If a folder has an index page (`readme.mdx` or `index.mdx`), you can also set `order` in the index page's frontmatter as a fallback. The `meta.json` `order` takes priority. + +--- + ## Markdown URLs Every page has a `.md` URL that returns raw markdown: From debd22e7def2c842431afaf04dfd41a34ec0b7a6 Mon Sep 17 00:00:00 2001 From: Rishabh Date: Thu, 14 May 2026 10:16:05 +0530 Subject: [PATCH 3/3] fix: folder sorting only via meta.json, not index page frontmatter Remove index page frontmatter order fallback for folder sorting. Folders sort only by meta.json order. Update docs to clarify. Co-Authored-By: Claude Opus 4.6 (1M context) --- examples/basic/content/docs/features.mdx | 2 +- packages/chronicle/src/lib/source.ts | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/examples/basic/content/docs/features.mdx b/examples/basic/content/docs/features.mdx index 8bbfdf9..313e341 100644 --- a/examples/basic/content/docs/features.mdx +++ b/examples/basic/content/docs/features.mdx @@ -190,7 +190,7 @@ docs/ Folders without `order` appear after all ordered folders. -If a folder has an index page (`readme.mdx` or `index.mdx`), you can also set `order` in the index page's frontmatter as a fallback. The `meta.json` `order` takes priority. +Folder sorting is controlled **only** by `meta.json` `order`. The index page frontmatter `order` does not affect folder position — it only controls the page's position within the folder. --- diff --git a/packages/chronicle/src/lib/source.ts b/packages/chronicle/src/lib/source.ts index 3e65ba5..89de861 100644 --- a/packages/chronicle/src/lib/source.ts +++ b/packages/chronicle/src/lib/source.ts @@ -143,8 +143,7 @@ function getOrder(node: Node, pageOrderMap: Map, folderOrderMap: if (node.type === 'page') return pageOrderMap.get(node.url); if (node.type === 'folder') { const folderPath = getFolderPath(node); - if (folderPath && folderOrderMap.has(folderPath)) return folderOrderMap.get(folderPath); - if (node.index) return pageOrderMap.get(node.index.url); + if (folderPath) return folderOrderMap.get(folderPath); } return undefined; }