feat: support draft frontmatter to hide pages

[rsbh]

Summary

• Add draft: true frontmatter support to hide pages from sidebar, prev/next nav, search, sitemap, and llms.txt
• Direct URL access to draft pages returns 404 (both SSR and /api/page)
• Prev/next navigation automatically skips draft pages

Usage

---
title: My Draft Page
draft: true
---

Test plan

• Draft page hidden from sidebar tree
• Direct URL returns 404
• /api/page returns 404 for draft
• Search excludes draft pages
• Prev/next navigation skips draft pages
• Non-draft pages unaffected
• 116 tests pass

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
chronicle	Ready	Preview, Comment	May 18, 2026 8:06am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d278b4d6-87ca-45f7-99b2-06681d766996

📥 Commits

Reviewing files that changed from the base of the PR and between 8f75a72 and ee77ad0.

📒 Files selected for processing (5)

• examples/basic/content/docs/features.mdx
• packages/chronicle/src/lib/source.ts
• packages/chronicle/src/server/api/page.ts
• packages/chronicle/src/server/entry-server.tsx
• packages/chronicle/src/types/content.ts

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added draft page support: mark pages as draft in frontmatter to exclude them from navigation and page listings, and prevent direct access (404 response).

Walkthrough

This PR adds draft page support to Chronicle. Pages can now be marked with draft: true in frontmatter; the source layer filters them from page trees and API responses, while server routes treat draft pages as 404 responses. An example draft page demonstrates the feature.

Changes

Draft Page Support

Layer / File(s)	Summary
Type definition and frontmatter extraction packages/chronicle/src/types/content.ts, packages/chronicle/src/lib/source.ts	Frontmatter gains optional draft?: boolean field; extractFrontmatter() exposes draft status and reading time; new isDraft() helper determines draft status from page data.
Source layer draft filtering packages/chronicle/src/lib/source.ts	filterDraftsFromTree() recursively removes draft pages from tree nodes; getPageTree() filters and caches draft-free trees; getPages() returns only non-draft pages.
API page handler draft response packages/chronicle/src/server/api/page.ts	API handler treats draft pages as not found: imports isDraft and returns 404 for both missing and draft pages.
Entry server draft filtering packages/chronicle/src/server/entry-server.tsx	Entry server refactors docs-page loading: imports isDraft, fetches raw page separately, then nullifies page when it is marked draft.
Example draft page examples/basic/content/docs/features.mdx	Demonstrates draft functionality by adding draft: true to features.mdx frontmatter.

Sequence Diagram

sequenceDiagram
  participant User
  participant EntryServer
  participant PageAPI
  participant SourceLayer
  participant PageData

  User->>EntryServer: Request docs page
  EntryServer->>SourceLayer: getPage(slug)
  SourceLayer->>PageData: Load frontmatter
  PageData-->>SourceLayer: Returns page with draft: true
  SourceLayer-->>EntryServer: rawPage (draft detected)
  EntryServer->>SourceLayer: isDraft(rawPage)
  SourceLayer-->>EntryServer: true
  EntryServer->>EntryServer: Set page = null
  EntryServer-->>User: 404 Not Found

  User->>PageAPI: GET /api/page/slug
  PageAPI->>SourceLayer: getPage(slug)
  SourceLayer->>PageData: Load frontmatter
  PageData-->>SourceLayer: Returns page with draft: true
  SourceLayer-->>PageAPI: page (draft)
  PageAPI->>SourceLayer: isDraft(page)
  SourceLayer-->>PageAPI: true
  PageAPI-->>User: 404 Not Found

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• raystack/chronicle#22: Changes to getPages() filtering out drafts directly affect sitemap generation that maps source.getPages() to document URLs.
• raystack/chronicle#19: Updates to getPages() draft filtering impact /llms.txt and /llms-full.txt routes that call source.getPages() for LLM output generation.
• raystack/chronicle#8: Changes to getPages() filtering drafts directly impact search indexing routes that build indexes from source.getPages().

Suggested reviewers

• rohilsurana
• rohanchkrabrty

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding support for draft frontmatter to hide pages from various surfaces.
Description check	✅ Passed	The description is directly related to the changeset, providing a clear summary of what draft support does, usage examples, and a comprehensive test plan.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/draft-frontmatter

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}