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.

[Rahulm2310]

Hello, I am a first timer. Is this issue available ?

[slorber]

@Rahulm2310 the feature is still available but as you can read, we are not sure yet of the design of this feature in the first place.

If you want to contribute to this feature, the first step is to define the behavior / API we actually want for this feature by studying the problem and writing some kind of an RFC proposal.

[antonygibbs]

Hi All,

Has there be any progress on this item? I feel that the initial request of simple excluding pages marked with 'draft' in the front matter is a great MVP, which can then be extended for other use cases from that point?

[anabellag7]

+1 here, is there an easy way to mark a page as "draft"?

[suntudo]

+1 here as well. We use the git-based Forestry.io CMS to edit our docs. Since it only connects to a single branch (in our case forestry-staging which we merge to main as needed), being able to mark doc pages as "draft" would be really useful.

I think using the same logic/functionality that the blog uses would be a great start.

[MattiaPrimavera]

+1 here. I'd be pleased to work on it, if the ticket is still available.
Shall we go for the draft header option in docs pages frontMatter MVP @slorber ?

The MVP might be the first step in the direction of adding support for both unlisted & draft to docs / pages / blog frontMatters for feature parity (as mentioned in the Pitch), and to support the different use cases as explained in

• this comment
• v1 blog documentation

[slorber]

Thanks @MattiaPrimavera , you can work on it but I suspect it's not so simple.

About unlisted I think it's a v1 feature we didn't port. We probably can do that in another upcoming PR, as it impacts various things including the sitemap plugin. Let's track this here: #5701

For now the goal is mostly to have the same draft frontmatter for both blog & docs.

FYI, the blog frontmatter works like this:

A boolean flag to indicate that the blog post is work-in-progress and therefore should not be published yet. However, draft blog posts will be displayed during development.

This means that for consistent behavior, docs with draft: true will not appear in prod (ie, the static page and route won't exist), and will only be available in dev.

Also, something to consider: should we display a sidebar category in prod if all its doc items are draft items? In production build means the sidebar category will end up being empty. (+ same question for a full tree of categories where all the other items are draft docs)

[slorber]

@suntudo can you clarify the Forestry use case? (cf my comment here: #5701 (comment))

It's not clear to me if you need a draft to be removed from the production site, or if the page should exist in prod (so that you can sharer a link) but not being referenced in sidebars/sitemaps etc... (in which case it's a separate "unlisted" feature tracked here: #5701)

[suntudo]

Hi @slorber

Yes, the issue is that we have multiple drafts on the staging site, but we can't merge them one at a time to production. So we need a feature to filter, or not build, pages that are marked as draft on production.

[juliampaul]

Hey @slorber , we've been wondering about this too... so this function would be useful to me :)

I have a setup with a test documentation site being built off one branch (for reviews, wip etc.) and a "publishing" site built off a main branch... we've got metadata "docVersion" in all our md pages where we show a badge for draft vs published, but I wanted to be able to "exclude" pages labelled draft from the PROD build (they will all be subpages so none of the sidebar items or menu would break doing this).

To me that sounds like a very similar use case for this functionality?

[slorber]

@juliampaul

but I wanted to be able to "exclude" pages labelled draft from the PROD build (they will all be subpages so none of the sidebar items or menu would break doing this).

Exclude means the URL is totally inaccessible in prod, not just "hidden" for secret users (ie company collaborators?)

If those docs don't appear in the sidebar, then how do you access them in dev?

Did you mean "navbar" instead of "sidebar"?

[juliampaul]

Exclude means the URL is totally inaccessible in prod, not just "hidden" for secret users (ie company collaborators?)

Yes - this is what I'd like but not in our TEST build, only in our PROD one.. we build our test website off one branch and the prod off main... we roll our test docs into our main branch with a merge but this just takes the lot whether it is actually ready to publish or not

If those docs don't appear in the sidebar, then how do you access them in dev?

mmm - you're right, more complicated than I thought - using my idea there would need to be two versions of sidebar wouldn't there? One for our test and one for prod? and then the prod one would need to be generated by referencing the stuff that's not to be published... doh! sounds complicated?

An alternative might be to apply a watermark to anything with the docVersion metadata value of DRAFT? I'm looking for a way to show a reader the diff between something that is version 0.1 of content, versus content that has had some 'attention' and is a lot more fit for purpose (which is what the published ones.... should be!) :)

Did you mean "navbar" instead of "sidebar"?

Nope - we auto generate sidebar from folder structures and I was thinking to exclude files/pages that have a status of DRAFT, navbar wouldn't be impacted in this case as it's pretty static.

Mmm - the usual method of applying this type of 'publication' scenario is SharePoint, where you have a specific 'publish' function for a file (though the whole 'use a Word doc and when it's ready to publish create a PDF' thing is dire!)

[Zenahr]

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.

The benefit of this feature would be to that it's a) more accessible for "novice" git users, b) more comfortable to work in general because it allows for non-linear workflows more so than with branches, c) it is more explicit and declarative.
I still think this feature would be highly beneficial in terms of QoL even though everything it sets out to solve could be done via git branching (some users might not even use version control).

[Zenahr]

@juliampaul

but I wanted to be able to "exclude" pages labelled draft from the PROD build (they will all be subpages so none of the sidebar items or menu would break doing this).

Exclude means the URL is totally inaccessible in prod, not just "hidden" for secret users (ie company collaborators?)

If those docs don't appear in the sidebar, then how do you access them in dev?

Did you mean "navbar" instead of "sidebar"?

Wouldn't one simple way of solving this be to have the draft status only affect how the static site is built? Meaning that no matter how and where a server is spun up the draft status doesn't affect anything.

Personally I think what draft should do is:

Don't show content in dev and prod (if you really want to preview the draft inside docusaurus just change draft to false and remember to switch it back once you're publishing the docs.

[Airkro]

Please add an option to disable draft option in front-matter, sometimes we want to see all docs.

[slorber]

@Airkro please open a separate issue to discuss that feature request, presenting your use-case and suggesting an API design