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"
  }

[delucis]

Thanks for this @gorohoroh. I think this is a bug, but I guess we haven’t really thought about how to handle drafts in the sidebar when you specify it explicitly like you are doing.

On the one hand, I kind of like the current behaviour: you asked to include a page in the sidebar, which won’t be built, so we warn you that you maybe don’t want to have that page as a draft.

Presumably the current workaround is to remove the sidebar item so the build will pass?

[gorohoroh]

Thanks for getting back to me so quickly, @delucis.

It would be fine if you in fact warned me, which is how you describe your vision in the second paragraph of your reply, but the problem is you don't warn me: you hit me in the head with a hammer by failing the build instead 😮

The workaround to remove the sidebar item will work, indeed, but I'd also argue that it defeats the purpose of using the draft property because you wouldn't see your draft in the sidebar in development mode, which means you'll likely forget that it exists, leading to clutter of unfinished work in the repo.

Ideally, the way I'd like it to work is as follows:

1. In production: if an article is set to draft: true, just ignore it and all references to it (including the sidebar). Don't fail the build. If production articles have outgoing links to draft articles that are excluded, let these links return 404, maybe warn about them in build output.
2. In development: include all drafts in the sidebar, show the draft warning inside the article as you do now, but also mark drafts with a badge in the sidebar. As a content developer, I'm interested in seeing the big picture of my drafts, which helps prioritize my work on them. For example, if I see that I have one draft in a section that is otherwise completed, I would probably prioritize completing that draft as opposed to working on drafts in a section that has many of them.

Not sure what other folks who are using draft: true are thinking about this, I'd be curious to know.

[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!)