Site with at least one article with draft: true in frontmatter doesn't build

[gorohoroh]

Hey, I've recently started using Starlight to develop a new content project. My workflow involves planning the structure first, creating stub pages based on the structure, and then iteratively adding content to the stubs.

The draft: true frontmatter property targets this scenario, but the problem is it seems to break the production build instead of excluding draft articles from it. If any of my articles has draft: true set, the build process (astro build) fails with the following message and stack trace:

 generating static routes 
15:07:04 ▶ @astrojs/starlight/routes/static/404.astro
15:07:04   └─ /404.html[AstroUserError] The slug `"guides/sample"` specified in the Starlight sidebar config does not exist.
  Hint:
    Update the Starlight config to reference a valid entry slug in the docs content collection.
    Learn more about Astro content collection slugs at https://docs.astro.build/en/reference/api-reference/#getentry
  Stack trace:
    at linkFromInternalSidebarLinkItem (file:///Users/gorohoroh/SOURCE/piiano/piiano-learn/dist/chunks/common_DDszJJ_Y.mjs:268:13)
    at file:///Users/gorohoroh/SOURCE/piiano/piiano-learn/dist/chunks/common_DDszJJ_Y.mjs:380:41
    at getSidebarFromConfig (file:///Users/gorohoroh/SOURCE/piiano/piiano-learn/dist/chunks/common_DDszJJ_Y.mjs:380:26)
    at generateRouteData (file:///Users/gorohoroh/SOURCE/piiano/piiano-learn/dist/chunks/common_DDszJJ_Y.mjs:465:19)

This particular draft article that the build is failing on is at /src/content/docs/guides/sample.md and has the following frontmatter:

---
title: "Markdown sample"
description: "..."
draft: true
---

Here's the definition of the draft article in astro.config.mjs:

export default defineConfig({
    integrations: [
        starlight({
            /*...*/
            sidebar: [
                {slug: 'guides/sample'},
                /* More sidebar items*/
            ],
        }),
    ],
});

However, the problem is not specific to this particular article and is reproduced with any article that has draft: true in frontmatter.

I would expect that if an article has draft: true, it's excluded from the production build along with its sidebar entry.

The current behavior kind of defeats the purpose of draft: true as prevents me from building and deploying when I have one or more articles marked as draft.

Is there something I'm doing wrong? Are any workarounds available to make it work the way I expect it to?

Thanks

[gorohoroh]

Oh, here's the list of package.json dependencies to identify my Astro and Starlight versions:

  "dependencies": {
    "@astrojs/starlight": "^0.28.3",
    "astro": "^4.15.3",
    "sharp": "^0.32.5",
    "@astrojs/check": "^0.9.4",
    "typescript": "^5.6.3"
  }

[gorohoroh]

BTW if as a result of this discussion there's a consensus on how to deal with this problem and the core team doesn't prioritize it high enough, I'm happy to try work on a PR.

[HiDeoo]

I don't particularly use drafts a lot myself, but after seeing the feature request, I asked around to a few users I know who do use the feature.

They seem to quite like the fail-safe of having a build error if they're explicitly adding a draft to the sidebar. For example, it seems to already have saved them from accidentally releasing a new feature, where the documentation spanning multiple pages was worked ahead of time as drafts, but once all the sidebar links were added at the release time, the build error warned them that one of the pages was still a draft and would not be published.

I guess there are pros and cons to both approaches.

[delucis]

That’s helpful user feedback, thank you @HiDeoo!

One thing we discussed when planning the drafts feature was the risk it brings because it introduces an explicit difference between development and production, which is the kind of difference that can be hard to debug or easy to miss in production. HiDeoo’s comment reminded me a bit of that: the subtlety of seeing a page in the sidebar during dev but then having it disappear in prod can easily trip you up, so a failing build is a “safer” approach because it alerts people to accidental or unexpected use of draft: true vs a page just quietly not existing and you don’t even notice.

I also think it might be possible to write a userland plugin which allows the behaviour outlined by @gorohoroh now I think of it. A Starlight plugin has access to the current command (i.e. 'dev' vs 'build) and can update the sidebar config. So in theory a plugin could glob src/content/docs/, parse the frontmatter to find entries with draft: true, and then filter out items in the sidebar that are drafts when building the site. (I’ll admit the need to glob and parse the content is not super fun though!)

[HiDeoo]

Based on that idea, I just released a new plugin using that approach:

• In development mode, sidebar links to draft pages are highlighted with a badge and an italicized label.
• In production mode, sidebar links to draft pages are automatically removed.

A plugin approach makes it easy for users to opt-in to this new and totally different behavior, gather interest and mostly feedback on it (and maybe even on other behaviors, who knows) and iterate on it faster (and this also does not mean that depending feedback, we cannot decide to reevaluate the core implementation later on, more data is always good).