Options to keep drafts in production builds

[Airkro]

Feature request:

Add an option to the config file, to keep drafts in production builds.

Use case:

Add draft: true to some docs' front-matter, bundle two sites, one of them hides the drafts as production, and another shows them for staging/internal.

[slorber]

We plan to have some kind of createFrontMatter() API (#5568) so that you can customize/update the frontmatter that Docusaurus reads directly from the config file. And you could use env variables in this hook.

Would your use-case be solved by such an imaginary config?

const showDrafts = process.env.SHOW_DRAFTS === "true";

const siteConfig = {
  markdown: {
    createFrontMatter: async ({
      plugin,
      filePath,
      defaultCreateFrontMatter // reuse existing utils parseFrontMatter
    }) => {
      const frontMatter = await defaultCreateFrontMatter(filePath);
      if (frontMatter.draft === true && showDrafts) {
        return {...frontMatter, draft: false}
      }
      return frontMatter,
    }
  }
};

SHOW_DRAFTS=true yarn docusaurus build 
SHOW_DRAFTS=false yarn docusaurus build 

[Airkro]

I can accept that. wait for createFrontMatter landing.

I don't want to change frontMatter.draft, some use cases may need it. but I can do some hacking instead.

[Airkro]

createFrontMatter landing maybe take years (in 3.0), before that, I want to inject a webpack loader by configureWebpack to do this.

But docusaurus always inject @docusaurus\mdx-loader after my loader, which means @docusaurus\mdx-loader always runs before my loader, maybe #6370 (also 3.0) is can solve this.

Seems like every way has been blocked. 😖

[Josh-Cena]

See https://docusaurus.io/community/release-process:

In practice, you can expect a new major version every 2–4 months.

[slorber]

I have no idea what you want to do this your Webpack loader, but I suggest to wait for the createFrontMatter hook. It's a high priority for me to ship this asap, as it's not too complex to build and unlock great flexibility. Expect it to land in canary/3.0-alpha soon

[Airkro]

Update:

Eventually, I found a way to inject a custom webpack loader, but docusaurus ignored drafts before the loader ran.

Now I override this line:

docusaurus/packages/docusaurus-plugin-content-docs/src/index.ts

Line 79 in d8c72fb

const env = process.env.NODE_ENV as DocEnv;

To:

const env = process.env.INTERNAL ? process.env.NODE_ENV : 'development' as DocEnv; 

When bundling the site on staging mode, set process.env.INTERNAL === true, draft pages will not ignore.

[Airkro]

In docusaurus 3.0, hacking this function is enough:

docusaurus/packages/docusaurus-utils/src/contentVisibilityUtils.ts

Lines 28 to 39 in bda8f14

	/**
	* A draft content will not be included in the production build
	*/
	export function isDraft({
	frontMatter,
	env,
	}: {
	frontMatter: {draft?: boolean};
	env?: Env;
	}): boolean {
	return (isProduction(env) && frontMatter.draft) ?? false;
	}

[Airkro]

I also use a remark plugin to add a draft admonition when bundling.

https://github.com/nice-move/remark-docusaurus/blob/0902b3311cdc285106de3c7d9013e240335459a5/lib/draft-admonition.mjs

Admonitions will show on draft pages, whether in dev mode or not.

But it can be remove when this feature landing: #8285

[Airkro]

New version for Docusaurus 3.0:

https://github.com/show-docs/remark-docusaurus/blob/722fbfd7eefe48ebce280ae137a71f9973d00578/lib/draft-admonition.mjs

[Airkro]

Related: https://docusaurus.io/feature-requests/p/passing-front-matter-to-remarkplugins

[Airkro]

In docusaurus 3.0, remark plugin can read frontmatter now.