Draft Mode for Pages

[jon-whit]

I want to work on the content of a documentation page before it officially gets published. Is there a way to turn on "draft-mode" with some label or annotation for a page that I'm working on?

docs/
.. work-in-progress.md # in draft mode
.. peer-reviewed.md

[slorber]

The concept of "draft mode" is ambiguous and something to define clearly.

What does it mean for a page to be a draft:

• it only appears in dev mode (npm run start) and not in prod (npm run build)?
• it appears on the production website, but is somehow "hidden"? (not in sitemaps, not indexed by Google?)
• it appears on the production website but it has some kind of draft marker/annotation?

What if you link from page1 to this page2 in draft mode: should we display a 404 page?

We already have a concept of draft: true in blog posts, but not for docs: https://docusaurus.io/docs/next/blog#header-options

Whatever we adopt, we should rather make the experience consistent across plugins and try to support all the use-cases the users will have for this draft feature

[nurulhudaapon]

For draft: true, the doc can be hidden from sidebar and error | log | warn etc. can be triggered based on configuration. But I think having a status with multiple supported value can be more useful. Or just being able do hide doc from sidebar is pretty common case. (hide_in_sidebard: true). Being able to archive doc is also common.

status: DRAFT | UNLISTED | UNPUBLISHED | PUBLISHED (default)

• DRAFT:

  • Production: Should be hidden from sidebar, should not be in sitemap, can't be referenced in published page.

  • Development: Should be visible in sidebar, warning should be shown if referened in published page.

• UNLISTED:

  • Production: Should not be in sidebar, should be in sitemap, can be referenced in other published page.

  • Development: Should be in sidebar sidebar with UNLISTED label

• UNPUBLISHED:

  • Production: Should not be in sidebar, should not be in sitemap but can be referenced in other page.

  • Development: Should be in sidebar with UNPUBLISHED label

  The following can be too much but these are common in other documentation site.

[slorber]

I like this status API, as it's more extensible and scalable compared to multiple booleans.
Not 100% sure about the details you assigned to each enum value though.

Something important to consider: the sitemap is generated by a plugin that does not know anything about the concept of frontmatter. To implement this, we probably need to modify the Docusaurus core so that it's possible to create a "draft route", ensuring it's not generated in the sitemap, and it's not referenced in any page created by other plugins.