Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(docs,blog,pages): add support for "unlisted" front matter - hide md content in production #8004

Merged
merged 54 commits into from
Nov 3, 2022

Conversation

jodyheavener
Copy link
Contributor

@jodyheavener jodyheavener commented Aug 24, 2022

PR started by @jodyheavener , finalized by @slorber

Motivation

Add uniform support for unlisted: true front matter to all 3 content plugins.

Unlike draft: true, unlisted content is accessible in production.

The goal is to give the ability to publish content in production but keep it "secret" until it's time to market it (like a new release blog post...). Being accessible in production build makes it easier to share a secret link to co-workers and ask for a review. The content will also be accessible in deploy previews that (unlike drafts).

Unlisted means that a Markdown file will be:

  • Visible in dev (docusaurus start)
  • "Hidden" in production (docusaurus build), but still available.

Unlisted items are "hidden" in production in multiple ways:

  • <meta name="robots" content="noindex, nofollow" /> metadata
  • excluded from sitemaps, Google, Algolia search, RSS feeds...
  • excluded from doc sidebar and doc pagination an navbar item type "doc"
  • a category linking to an unlisted doc can't be navigated, same for the respective category breadcrumb item
  • excluded from blog sidebar and blog pagination
  • excluded from docs/blog tags pages
  • only the users having the link can access it

This PR also adds the missing draft: true support for the content pages plugin.

This PR is quite significant, won't be backported

Unlisted pages have a banner displayed in production:

CleanShot 2022-11-03 at 13 33 44

(we can probably improve this later, it probably makes sense for DX to also display such a banner in dev mode for both draft/unlisted => #8285)

Test Plan

I added multiple dogfood content to our own website.

It is possible to test the production mode locally faster with this secret env variable: SIMULATE_PRODUCTION_VISIBILITY=true yarn start:website

Blog

Blog tags

Docs

Docs tags

Docs category links:

Pages

Sitemap

Related issues/PRs

Closes #5701

@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Aug 24, 2022
@jodyheavener jodyheavener changed the title Exclude unlisted docs, pages, and blog posts feat(content-docs, content-pages, content-blog): exclude content marked as unlisted Aug 24, 2022
@netlify
Copy link

netlify bot commented Aug 24, 2022

[V2]

Name Link
🔨 Latest commit 3c81af8
🔍 Latest deploy log https://app.netlify.com/sites/docusaurus-2/deploys/6363b9f03569640009342ddb
😎 Deploy Preview https://deploy-preview-8004--docusaurus-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

@github-actions
Copy link

github-actions bot commented Aug 24, 2022

⚡️ Lighthouse report for the deploy preview of this PR

URL Performance Accessibility Best Practices SEO PWA Report
/ 🔴 41 🟢 97 🟢 100 🟢 100 🟢 90 Report
/docs/installation 🟠 76 🟢 100 🟢 100 🟢 100 🟢 90 Report

@slorber slorber added the pr: new feature This PR adds a new API or behavior. label Sep 7, 2022
Copy link
Collaborator

@slorber slorber left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Looks like a very good start 👏

See my comments, will review the rest in 2+ weeks after my holiday ;)

packages/docusaurus-plugin-content-docs/src/frontMatter.ts Outdated Show resolved Hide resolved
packages/docusaurus-plugin-content-docs/src/globalData.ts Outdated Show resolved Hide resolved
packages/docusaurus-plugin-content-docs/src/index.ts Outdated Show resolved Hide resolved
website/_dogfooding/_docs tests/test-unlisted.md Outdated Show resolved Hide resolved
website/_dogfooding/dogfooding.config.js Outdated Show resolved Hide resolved
website/_dogfooding/docs-tests-sidebars.js Outdated Show resolved Hide resolved
@slorber
Copy link
Collaborator

slorber commented Oct 20, 2022

@jodyheavener do you want to do some edits? Otherwise I'll try to complete and merge it

@slorber
Copy link
Collaborator

slorber commented Oct 21, 2022

🤯 this feature is full of little edge cases to consider. Still WIP, but it's progressing.

I created a better docs dogfood dataset here, and it works nicely:
https://deploy-preview-8004--docusaurus-2.netlify.app/tests/docs/tests/visibility/

There are some yet-to-be-resolved comments above, and notable the handling of tags pages and paginated lists.

Will try to complete all this next week

Copy link
Collaborator

@slorber slorber left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR is good to merge 👍

I'll check 1 or 2 edge cases I'm thinking about tomorrow but otherwise it's complete

Note: it's a lot of code, I won't backport it in 2.x and we'll ship it in 3.0

@slorber
Copy link
Collaborator

slorber commented Nov 3, 2022

PR is good to merge! That wasn't an easy one 🤪 tons of little edge cases to consider.

@slorber slorber changed the title feat(content-docs, content-pages, content-blog): exclude content marked as unlisted feat(content-docs, content-pages, content-blog): add support for "unlisted" front matter to hide content in production Nov 3, 2022
@slorber slorber changed the title feat(content-docs, content-pages, content-blog): add support for "unlisted" front matter to hide content in production feat(docs,blog,pages): add support for "unlisted" front matter to hide content in production Nov 3, 2022
@slorber slorber changed the title feat(docs,blog,pages): add support for "unlisted" front matter to hide content in production feat(docs,blog,pages): add support for "unlisted" front matter - hide md content in production Nov 3, 2022
@slorber slorber merged commit 683ba3d into facebook:main Nov 3, 2022
@rabernat
Copy link

rabernat commented Jan 4, 2023

Thanks for this great new feature! Are there any plans for a release soon?

@slorber
Copy link
Collaborator

slorber commented Jan 4, 2023

Not planned to be backported in 2.x and 3.x is not so close yet so if you need it you need to use a canary release (it's quite stable, that's fine)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA pr: new feature This PR adds a new API or behavior.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Blog/docs: unlisted
5 participants