Warning about build issue for draft pages

[dagilleland]

What page of the docs did you find an issue on?

https://starlight.astro.build/reference/frontmatter/#draft

Describe the issue

When a sidebar item is explicitly listed in astro.config.mjs and that item's page has draft: true in the frontmatter, the build will fail. This is already identified in the discussion #2545.

For example, if the 'Author Guide' page has draft: true in its frontmatter, then the build will fail with [AstroUserError] The slug "about/author-guide" specified in the Starlight sidebar config does not exist. (assuming the following explicit configuration).

	sidebar: [
		{
			label: 'About',
			items: [
				{ label: 'Author Guide', slug: 'about/author-guide'},
				{ label: 'Start Here', slug: 'about/start-here' },
				{ label: 'Bonus Resources', slug: 'about/bonus' },
			],
		},
	...

---

Recommendation: Add a warning regarding this in the docs. Here's a possible writeup:

Flagging a document as a draft is only supported in production builds when the sidebar configuration for the document is part of an autogenerated list of items. If you have a sidebar group with an explicit reference to your draft document, the production build will fail.

One drawback in this would be that the file - frontmatter.md - is regular Markdown instead of an MDX file, so Starlight's own <Aside> wouldn't work without committing to a change from .md to .mdx.

### `draft`

**type:** `boolean`  
**default:** `false`

Set whether this page should be considered a draft and not be included in [production builds](https://docs.astro.build/en/reference/cli-reference/#astro-build) and [autogenerated link groups](/guides/sidebar/#autogenerated-groups). Set to `true` to mark a page as a draft and make it only visible during development.

<Aside type='caution'>
Flagging a document as a draft is only supported in [production builds](https://docs.astro.build/en/reference/cli-reference/#astro-build) when the sidebar configuration for the document is part of an autogenerated list of items. If you have a sidebar group with an explicit reference to your draft document, the production build will fail.
</Aside>

What operating system are you using?

Windows

What browser are you using?

Edge

Participation

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

[HiDeoo]

Thanks for the feedback 🙌

Considering the content already says:

Set whether this page should be considered a draft and not be included in production builds and autogenerated link groups.

It feels to me like the first part of the suggested addition is a bit repetitive.

My thinking may be that we could add a bit more details to the description without having to rely on an aside.

Set whether this page should be considered a draft and not be included in [production builds](https://docs.astro.build/en/reference/cli-reference/#astro-build) and [autogenerated link groups](/guides/sidebar/#autogenerated-groups).
[Internal sidebar links](/guides/sidebar/#internal-links) to draft pages are not supported and will error at build time.
Set to `true` to mark a page as a draft and make it only visible during development.

I'd like to get more opinions on this before making the change. This could be a small topic for discussion in the Talking & Doc'ing sessions we're publicly hosting every Thursday on Discord. This would be a great opportunity to get more feedback from more people and documentation experts.