Support for draft documentation pages

[huijing]

What version of starlight are you using?

0.11.2

What is your idea?

To be able to support draft documentation pages through a frontmatter variable (like draft: true or something), such that those pages are not included during the production build.

Why is this feature necessary?

My tech writing team usually works on our documentation projects from a top-down planning approach, i.e. the structure of the content is scaffolded onto the site before the content is completed. Thus, there are situations where they would like some pages to be marked as drafts, excluding them from the production build but have the files still committed and merged into the main repository.

Do you have examples of this feature in other projects?

• https://docs.astro.build/en/guides/upgrade-to/v3/#deprecated-markdowndrafts
  • Astro v3.0 needs us to manually filter out pages with the appropriate frontmatter property
  • This would involve a modification to Starlight code to implement the filter

Participation

• I am willing to submit a pull request for this feature.

[HiDeoo]

Sharing some additional infos I posted on Discord:

To be properly supported, I think the main getCollection() call in Starlight would need to be updated to use an optional filter callback and filter out drafts.

An important thing to consider too is how to surface them? I guess they should be visible during development and maybe with a notice at the top like fallback content?

[huijing]

When you say notice, did you mean something like how we do for missing translations?

[HiDeoo]

Yeah, that was my initial thought, something only visible during development with maybe a message saying it's a draft and that the page won't be published when build for production or something like that. But maybe it's not helpful?

[delucis]

I personally think it could be helpful and would help with the problem of “Help! My page shows up in dev but not when I build.” That is always a risk with features like this that introduce a dev/prod difference.

[huijing]

I 100% think it would be helpful.

[HiDeoo]

Starlight 0.22.0 added a new draft frontmatter option to exclude a page from production builds.

---
# Exclude this page from production builds
draft: true
---