Proposal: add unlisted/draft banners in dev mode

[slorber]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

#8004 brings support for unlisted to all 3 content plugins, including a banner to make it clear a content is unlisted:

I think it could improve the DX to also display such a banner in dev for both draft: true and unlisted: true

Note in our current implementation, the doc metadata.unlisted is never true in dev mode so this metadata is not a good way to display the banner in dev. We could read frontMatter.unlisted directly instead.

Self-service

• I'd be willing to do some initial work on this proposal myself.

[Airkro]

Thanks Docusaurus 3.0, now is easy to doing this by create a remark plugins:

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

[dkoprowski]

I can see the "Unlisted page" banner in production mode.

I thought that it would only be visible in the dev mode; when I add unlisted: true to the Front Matter of either page or blog post, I can see the banner in production mode.

Steps to reproduce:

1. add unlisted: true to the Front Matter of either page or blog post
2. npm run build

• I received the following info: [INFO] [en] Creating an optimized production build...

3. npm run serve (or put "build" folder content on any server)
4. the "Unlisted" banner is visible on a page with unlisted: true flag in prod and dev modes

Expected result: The "Unlisted" banner is not visible in production mode.

Should I create a separate issue for that?

Additional info:

    "@docusaurus/core": "^3.4.0",
    "@docusaurus/plugin-ideal-image": "^3.4.0",
    "@docusaurus/preset-classic": "^3.4.0",

[OzakIOne]

@dkoprowski
The behavior seems to be expected according to the documentation for unlisted documents

If you expect a different behaviour indeed you should create a separate issue though i'm not sure if we'll modify this behavior directly unless there is a demand for that.

Also it might be possible to achieve what you request by creating a remark plugin to remove the banner of unlisted content only during production build (i'm not sure about that)

[slorber]

Yes it's expected to see the banner in production mode, this way you know that the page is unlisted and don't forget to remove the flag once ready. I'd like to keep it this way.

But this can easily be changed by swizzling @theme/DocItem/Layout and not rendering the banner in the doc layout. This means that until we fix this issue (showing banners in devs), you will get no banner at all in both dev/prod modes.

The banner is not in the Markdown so it can't be removed with a remark plugin. At best you can remove the unlisted front matter, but then your doc becomes listed (which removes the banner, but may not be what you want)

[gsouf]

@slorber I understand the behavior, however I'd like to note that there are cases where we want to have documentation accessible only by private link, but still be unlisted. It looks unprofessional to keep showing this banner and my instinct is that this shouldn't display in production at all.

It seems to be reasonable to assume that most users would rather not have this banner in production, and a flag to disable it would be welcome.

That being said, a dedicated note in the documentation with further details on how to deal with @theme/DocItem/Layout for that specific case would be helpful.

please, consider this as a constructive feedback.

[slorber]

@gsouf there's no perfect solution, and as a regular docusaurus user for my own needs, I have often forgotten to remove unlisted: true from blogs I wanted to publish. Removing the banner prevents the author from noticing the flag is still there, and the content is never indexed.

"it looks unprofessional" really depending on the context.

We'd rather not document such behavior because many components are theme implementation details and we don't necessarily want them to become public api surface, and maintain retrocompatibility on them. This reduces our ability to refactor things.

However I could recommend to swizzle this theme component that isolates the behavior:

export default function ContentVisibility({metadata}: Props): ReactNode {
  const {unlisted, frontMatter} = metadata;
  // Reading draft/unlisted status from frontMatter is useful to display
  // the banners in dev mode (in dev, metadata.unlisted is always false)
  // See https://github.com/facebook/docusaurus/issues/8285
  return (
    <>
      {(unlisted || frontMatter.unlisted) && <Unlisted />}
      {frontMatter.draft && <Draft />}
    </>
  );
}

It receives the full metadata object (more than what the props declare), including front matter, and you can conditionally render the banner you want for all of docs, blog and pages.