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(content-docs): displayed_sidebar front matter #5782

Merged
merged 27 commits into from
Jan 19, 2022

Conversation

Josh-Cena
Copy link
Collaborator

@Josh-Cena Josh-Cena commented Oct 25, 2021

Motivation

Resolve #5686. This PR:

  • Adds a displayed_sidebar front matter option;
  • Deprecates the ref item type (in documentation);
    • We will not deprecate the ref because it's a nice alternative to setting both pagination_* and displayed_sidebar front matter.
  • Rewrites the sidebar documentation to make it (hopefully) far less confusing by providing a rigorous spec for shorthands and pagination generation.

We will add hide_sidebar in another PR where we hopefully port the same DX to other front matter options like hide_table_of_contents.

There's a slight behavior inconsistency between ref and doc when generating pagination: ref are completely ignored while doc will become the next and prev. I personally think that's fine.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Added two sidebar cases

Some unit tests

@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Oct 25, 2021
@netlify
Copy link

netlify bot commented Oct 25, 2021

✔️ [V2]
Built without sensitive environment variables

🔨 Explore the source changes: aa6240e

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/61e3a28793201c000858562c

😎 Browse the preview: https://deploy-preview-5782--docusaurus-2.netlify.app

@github-actions
Copy link

github-actions bot commented Oct 25, 2021

⚡️ Lighthouse report for the changes in this PR:

Category Score
🟠 Performance 74
🟢 Accessibility 98
🟢 Best practices 93
🟢 SEO 100
🟢 PWA 92

Lighthouse ran on https://deploy-preview-5782--docusaurus-2.netlify.app/

@Josh-Cena Josh-Cena marked this pull request as draft October 25, 2021 23:03
@Josh-Cena Josh-Cena changed the title feat(content-docs): displayed_sidebar front matter & displayThisSidebar item option feat(content-docs): displayed_sidebar front matter Oct 25, 2021
@Josh-Cena Josh-Cena added the pr: new feature This PR adds a new API or behavior. label Oct 28, 2021
Signed-off-by: Josh-Cena <sidachen2003@gmail.com>
@Josh-Cena Josh-Cena added the status: blocked This issue is blocked by another issue or external dep and can't be pushed further. label Nov 14, 2021
@Josh-Cena Josh-Cena removed the status: blocked This issue is blocked by another issue or external dep and can't be pushed further. label Dec 3, 2021
@Josh-Cena Josh-Cena added the status: awaiting review This PR is ready for review, will be merged after maintainers' approval label Jan 16, 2022
@Josh-Cena Josh-Cena marked this pull request as ready for review January 16, 2022 04:20
@Josh-Cena
Copy link
Collaborator Author

@slorber Please review this for the next week. Let's make it into the next release because I'm constantly asked of this on Discord.

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, that looks great 👍


The `ref` type is identical to the [`doc` type](#sidebar-item-doc) in every way, except that it doesn't set the association. It only registers itself as a link but doesn't take part in generating navigation metadata. When [generating pagination](#generating-pagination) and displaying sidebar, `ref` items are completely ignored.
When you add doc Y to sidebar X, it creates a two-way binding: sidebar X contains a link to doc Y, and when browsing doc Y, sidebar X will be displayed. But sometimes, we want to break either implicit binding:
Copy link
Collaborator

Choose a reason for hiding this comment

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

break either implicit binding?

I'm not native but that sounds weird to me

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Break the forward binding, or backward binding 😄 I think it makes sense

Copy link
Collaborator

Choose a reason for hiding this comment

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

ok, seems good enough, we can improve later if anyone complains :D

@slorber slorber merged commit 45f1b81 into facebook:main Jan 19, 2022
@Josh-Cena Josh-Cena deleted the display-sidebar branch January 19, 2022 15:01
@Josh-Cena Josh-Cena removed the status: awaiting review This PR is ready for review, will be merged after maintainers' approval label Jan 19, 2022
@blling
Copy link

blling commented Jan 21, 2022

@Josh-Cena It is great, when to release?

@Josh-Cena
Copy link
Collaborator Author

Probably in a week or two, no solid plan yet :)

@blling
Copy link

blling commented Jan 21, 2022

@Josh-Cena thanks for your hard work! :-) BTW, how to download a .md file from the docs/assets dir ? it seems docusaurus always treat .md as a page but not a file for download.

@blling
Copy link

blling commented Jan 25, 2022

@Josh-Cena could you give me a advice to download a .mdfile from the docs/assets dir? :-)

@Josh-Cena
Copy link
Collaborator Author

You can use the @site alias to tell Docusaurus that this file is an asset: [download this MD](@site/docs/assets/file.md)

@blling
Copy link

blling commented Jan 26, 2022

@Josh-Cena download worked, but it is display in the sidebar, i use autogenerated sidebar, how to avoid the .md file from display in the sidebar in docusaurus-2.0.0-beta.14

图片

@Josh-Cena
Copy link
Collaborator Author

@blling Please don't use GitHub as a support forum. We have a lot of other channels: https://docusaurus.io/community/support

@Josh-Cena
Copy link
Collaborator Author

For your question, we don't have a way to exclude things from the autogenerated slice as of now, so your only chance is to put this file out of the docs directory.

@blling
Copy link

blling commented Jan 26, 2022

@Josh-Cena maybe add a sidebar_ignore front matter is great :-)

I will use other channels from tomorrow,thx for your hard work,i like this doc tool :-)

@slorber
Copy link
Collaborator

slorber commented Jan 26, 2022

For your question, we don't have a way to exclude things from the autogenerated slice as of now, so your only chance is to put this file out of the docs directory.

Hmm, I think using the _file.md prefix should work no?

@Josh-Cena
Copy link
Collaborator Author

Ah yeah, that should work too 🤔

@blling
Copy link

blling commented Jan 27, 2022

@slorber @Josh-Cena there is a warning when use _file.md
图片

图片

@slorber
Copy link
Collaborator

slorber commented Jan 27, 2022

I see, but it works right?

@blling
Copy link

blling commented Jan 28, 2022

I see, but it works right?

it works :-)

@slorber
Copy link
Collaborator

slorber commented Sep 28, 2022

@Josh-Cena we don't have any ref api doc for this: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter

Do you want to add it? Otherwise I'll do it

@Josh-Cena
Copy link
Collaborator Author

Interesting—yes, you can send a PR and I may take a look

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.

front matter option "displayed_sidebar" & "hide_sidebar"
5 participants