Docusaurus: Draft feature for Doc Pages Frontmatter

[MateuszDabrowski]

🚀 Feature

The blog post has a feature of draft tag in frontmatter.
It would be great to have the same option for Doc pages that are under construction - to be able to work on them locally, but not publish via deployment (even unlinked, they are visible in the Algolia search for example).

Have you read the Contributing Guidelines on issues?

Yes

Motivation

I want to make the doc writing easier on production environments.

Pitch

This feature will not only improve feature parity between frontmatter of blog and doc, making it easier to work on both at the same time, it will also make working on extensive docs much easier without the need to block the deployment.

[slorber]

Yes, makes sense, and can also be added to markdown pages as well.

Btw they should also be filtered by the sitemaps plugin so that SEO don't index them. Or maybe the pages can still be there but we should just add a noindex nofollow in metas, is that enough?

If someone wants to work on this, that's cool, otherwise I'll do it

[MateuszDabrowski]

Filtering them fully from production would be a better way from my perspective, as we just don't want users to get there (either via google or algolia or else). Great point with pages!

[MateuszDabrowski]

Optional feature: links pointing to resource in draft mode could show "Work in progress" page instead of 404.

[GMarkfjard]

@slorber As a part of my masters studies I'm tasked with contributing to some open-source projects. This issue seems to be a great start and I would love to be assigned to this issue!

As a contribution to the discussion I do agree that a human readable message is to prefer over a 404!

[slorber]

@GMarkfjard yes please submit a PR 👍

I do agree that it can be convenient and quite simple to filter these draft pages in production, so that the pages only exist in dev.

However, I do think that it should be possible to have draft pages exist in production, yet being filtered on the homepage.

I do use this workflow on my own blog to get early reader reviews (by sending a real production link) before making the blog post appear on the homepage and marketing it.

So, maybe the plugins could have an option to say whether or not draft content should be available in production?

[amimas]

So, maybe the plugins could have an option to say whether or not draft content should be available in production?

I agree that it should be a configurable option. Or at least not expect everyone to have their drafts publicly available even if it's not reachable from another page.

But I wonder if this is only about drafting new docs. What if someone wants to make changes to several existing docs as draft?

Also, I think the term draft is a bit overloaded here. In a typical setup, all docs are already in "draft" mode and people can review them in the PR. You also have a netlify preview site for each PR. That can be easily setup even without netlify. So, I'm not really sure if this feature request is really adding any benefits.

[slorber]

But I wonder if this is only about drafting new docs. What if someone wants to make changes to several existing docs as draft?

Afaik we don't have the concept of "edit draft" and it'll be complicated to implement in markdown as we are not a CMS, but you could emulate this by copying the source doc and putting draft: true on the copy, or using a PR.

To me, draft frontmatter is only useful if you want the thing to be on master, and appear in production site so you can share it privately (cf. what I do with my blog posts to get reviews). If you don't want it in prod, as you are git based, you'd rather use a git branch and PRS/deploy previews instead, and only merge it when not in draft anymore.

[amimas]

If you don't want it in prod, as you are git based, you'd rather use a git branch and PRS/deploy previews instead, and only merge it when not in draft anymore.

That's the setup I have. Whether you use netlify or some other service, you can deploy the site from every branch. And there's your "draft". When changes are finalized and merged into the main branch, the changes will be in production site.

That's why I'm still not seeing a lot of benefit of the proposed feature. Also, i agree with @slorber about the fact that this is not a CMS. It's a static site generator.