Drafts filtering behavior, configuration, flags, and docs needs cleanup.

[bradobro]

What version of astro are you using?

2.6.1

Are you using an SSR adapter? If so, which one?

None

What package manager are you using?

pnpm

What operating system are you using?

Mac

What browser are you using?

Firefox

Describe the Bug

This may simply be a problem with my understanding of the behavior or a clarification in the docs.

Background

I've looked at #440 and the docs regarding the build --drafts flag and the markdown.drafts configuration.

It looks to me like:

• the --drafts flag isn't wired in to code yet
• there's no strong convention for using the markdown.drafts flag. AFAICT it's ignored by the collections API, the stock blog template, and other 3rd party templates (my stackblitz example only demonstrates that the draft pages are built whether or not the flag is present).
• There's not clarity on how drafts filtering should happen (Sitemaps include filtered pages and drafts #7087, [MDX] Docs: Custom components for imported mdx #5055)

Astro's collection API is a nice addition, and it prevents 1000 ad-hoc almost compatible similar implementations from sprouting up. The idea of having items in a collection that aren't ready for production (drafts) seems like a good thing to have a convention around.

Proposal

This will take some discussion, but to start the discussion, I propose that:

• When an item is marked draft it is included in the by default in astro dev and excluded by default in astro build, which can be overridden by config.markdown.drafts, which can be overridden by the --drafts flag.

• When drafts are excluded, they're excluded everywhere. They don't exist--not their empty folders, their html, nor their RSS feeds. This prevents accidental info leaks and other embarrassments.

• This behavior should be implemented in the collections API.

Next Steps

All those assertions are debatable, but I think form a good starting point. If we can agree on behavior and api, I'd be willing to submit a PR.

35055

Link to Minimal Reproducible Example

https://stackblitz.com/github/bradobro/astro-test-drafts?file=README.md

Participation

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

[bholmesdev]

Thanks for sharing this @bradobro! Totally agree on conventions. This was a strong feature at launch that was slowly neglected by new features (content collections and sitemaps namely). We have a roadmap discussion repo where we propose ideas like this. I invite you to start a discussion there with the Proposal template! Should fit the background and proposal (which I see as goals) nicely.

[natemoo-re]

Thanks for opening such a detailed issue! @bholmesdev shared some insights into the history of this feature, and after discussing with the team we definitely agree that it's time to revisit drafts behavior. We're trying to put together a plan for breaking changes coming in Astro 3.0, and this is an issue we've bookmarked to revisit. Stay tuned!

[bradobro]

Hey @natemoo-re and @bholmesdev thanks for the response. Travel has taken my attention from this a bit. Would you still like my comments about this feature in an existing discussion (or start one as @bholmesdev mentioned)?

[natemoo-re]

After much discussion with the team, we've made the decision to deprecate the drafts feature in Astro 3.0. It was only ever supported in .md and .mdx files inside of the src/pages/ directory, but never implemented in the Content Collections API.

Drafts were introduced back before Astro 1.0, when Astro was purely a static site generator and .md/x pages were our recommended way of working with content. Since then, Astro's capabilities and scope have grown to accommodate many different hosts and server runtimes. As such, we feel that the drafts feature as originally designed doesn't fit with our current approach to content.

Despite this deprecation, we understand the need for previewing unpublished content. There is an ongoing roadmap discussion about supporting preview deployments for headless CMSs. Hopefully whatever eventual API emerges from that discussion can also accommodate local content. In the meantime, manually filtering your Content Collection posts using this approach is a perfectly valid way to implement drafts in userland.

await getCollection("post", ({ data }) => import.meta.env.DEV || !data?.draft))

[natemoo-re]

@bradobro if you'd like to start a dedicated discussion on our roadmap for what the future of draft support specifically could look like, we'd love to continue this conversation over there! Really appreciate the thought you've already put into this.