Content tagging for single-sourcing

[ArtFlag]

🚀 Feature

The idea of single-sourcing is to generate different outputs with one set of source files.
A typical example is for private and public docs, where the private docs are a superset of the public docs.

This is done by tagging content that can be included or excluded at build time.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

Managing internal docs and public docs from one repo makes things a lot more easy, espcially when it comes to linking and information architecture.

Pitch

Flare, Sphinx and other docs-specific tools allow writers to tag content, very much like Docusaurus uses admonitions.

Sphinx example

non-tagged content
 
.. only:: my-admin-content-tag
 
   some tagged text

non-tagged content

And you can include this tag in the output with

sphinx-build -t my-admin-content-tag #this builds the admin docs

That's a great system to not limit the number of outputs.

Example with Docusaurus

Maybe 1 new admonition would do the trick as a first step, for instance, internal:

That's public text. It will be in the internal and public output.

:::internal
That bit is internal only and will not appear in the public output.
:::

Then we could build the internal docs with a flag:

yarn build --internal

Giving us:

That's public text. It will be in the internal and public output.

That bit is internal only and will not appear in the public output.

Would this be achievable?

[slorber]

@ArtFlag , we don't currently support this in core, but that may already be possible to build in userland

• You can include/exclude docs from sidebars dynamically (see RFC: docs version configurations #3285 (comment)) (not ideal because it's per doc, and the doc would just be "hidden", still published without sidebar)

• You can toggle a remark plugin for public deployments that would remove all content with ::: internal, similar to what admonition is doing except you remove the content instead of rendering an admonition

• You can create a <TagProtected tag="internal> component that you'd use in MDX This component can use site config (like the customFields) to decide to render or not.

The 3rd solution is probably the simplest.

[Josh-Cena]

This is probably too opinionated to be officially supported, and it can be easily implemented in the userland. Closing in favor of #5701