Support 'draft' mode in sidebar

[aschrijver]

What version of starlight are you using?

0.34.2

What is your idea?

The frontmatter setting draft: true allows marking single pages as a draft. But only when they are not part of a regular group in astro.config.mjs sidebar config. These entries must be commented out for the build to succeed. As the docs state:

Because draft pages are not included in build output, you cannot add draft pages directly to your site sidebar config using slugs. Draft pages in directories used for autogenerated sidebar groups are automatically excluded in production builds.

Given the feature description for draft..

Set whether this page should be considered a draft and not be included in production builds. Set to true to mark a page as a draft and make it only visible during development.

.. "make it only visible during development" is not fully accurate. I want to see the full sidebar during development with draft pages and groups all present, while I still have the need to build the code without an error. I shouldn't have to edit the config for a build to succeed or have multiple configs for dev and prod.

Why is this feature necessary?

The current implementation of draft feels unfinished. During development people should be able to work on entire documentation sections that are in draft, and see / refine the content hierarchy along with the content itself at their localhost:4321 site preview.

Ideally one setting of draft in frontmatter should be enough, but a draft setting might be part of the config too. The sidebar might have UI indicator of the pages/groups that are in draft.

Do you have examples of this feature in other projects?

No response

Participation

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

[aschrijver]

I did not notice that the issue selector 'demoted' my request to become a Discussion, so after the fact posting some related discussions.

The problem is addressed in #2545 by @gorohoroh who says:

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.

@delucis answers, and then the discussion continues on various options and challenges. It starts with..

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.

@gorohoroh describes the desired functionality in the same way I did above:

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.

[aschrijver]

To the concern expressed in #2545 (reply in thread) by @delucis about explicit differences between dev and prod leading to problems..

How the build behaves might be configurable. Want errors? Or warnings? Or just info "Page 'foobar' in draft mode, omitted from build".

[aschrijver]

As for my particular use case, which I think is interesting to mention. Our documentation site is to be a crowdsourced artifact with a growing number of public pages, but significant chunks of the docs and entire content hierarchies possible to be prepared in draft mode. Content strategy, optimization of the hierarchy are part of the workflow. The workflow itself is cheap man's CMS-like where a growing group of authors use git and local dev authoring and synchronise via PR's to the origin repo in the code forge.

[HiDeoo]

Thanks for the feedback 🙌

I did not notice that the issue selector 'demoted' my request to become a Discussion

This is actually how we organize feedback in the Starlight repo, we use issues for bugs only, and discussions for feature requests and general feedback.

I see you found #2545 where we already discussed such behavior in the past.

Cross-posting a comment I just made there after releasing a new plugin that implements this new behavior:

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).

[aschrijver]

In the docs for the plugin this text is confusing:

adding a sidebar link to a draft page and forgetting to remove the draft status before deploying

Do you mean:

adding a link to a page that is in draft mode and forgetting to remove the draft status of that page before deploying

?

[aschrijver]

A further improvement would be to log warnings for each page that is in draft, so it is still noticable in the log at build time.

[aschrijver]

Just added the new plugin, and it works right away according to instructions. 🎉

My use case might be the exception to the rule, where there are typically always a bunch of pages in draft. The disadvantage in the current UI is that the draft label make sidebar entries no longer fit a single line and the sidebar look cluttered.

Musing on how to avoid this..

For my use case the sidebar entry text being italicised would be enough, maybe with an addition distinctive text color. And not show tha draft label that impact the layout. Possibly have the ability to specify a CSS class to style draft entries. Instead of multiple draft labels the sidebar might contain a single entry "warning: contains draft pages" in similar fashion as shown on individual draft pages, and acting as a legend for the visual style of such pages.

[HiDeoo]

I have collected some other feedback through other channels that I'm planning to address tomorrow and some of it seems to overlap with some of the feedback you provided.

Note that if you have any additional feedback related to the plugin specifically, feel free to share it on the plugin's GitHub repository instead of the Starlight one, as it will be easier to track and address quickly 🙌

[aschrijver]

No problem. I just created 2 issues with the feedback from the comments above.

• Log warnings during build HiDeoo/starlight-auto-drafts#3
• Improve visual style of draft indicator UI HiDeoo/starlight-auto-drafts#4