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.

Sign up for GitHub

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

Jump to bottom

Add breadcrumbs to docs #6096

Closed
2 tasks done
Josh-Cena opened this issue Dec 11, 2021 · 5 comments · Fixed by #6517
Closed
2 tasks done

Add breadcrumbs to docs #6096

Josh-Cena opened this issue Dec 11, 2021 · 5 comments · Fixed by #6517
Labels
feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this

Comments

@Josh-Cena
Copy link
Collaborator

Josh-Cena commented Dec 11, 2021 •
edited
Loading

Have you read the Contributing Guidelines on issues?

Description

Docs should have breadcrumbs in addition to sidebar.

Has this been requested on Canny?

No

Motivation

I've just built this feature for someone: PatelN123/Digital-Support-Notes#1 (That person just wanted the primary category, but I did extract the entire breadcrumb list)

It wasn't quite ergonomic, and I think it would make sense to make itself into the core.

API design

It would be opt-in, something like showBreadcrumbs in the docs plugin. I think we can also set a metadata to help with SEO?

If we don't want an opinionated implementation for the UI component, we can just implement a useBreadCrumbs in theme-common and let users wrap DocItem to implement what they want.

Have you tried building it?

Yes, see that PR for how I did it.

Self-service

  • I'd be willing to contribute this feature to Docusaurus myself.
@Josh-Cena Josh-Cena added feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this labels Dec 11, 2021
@slorber
Copy link
Collaborator

slorber commented Dec 15, 2021

Yes, we could add that option, and probably turn it on by default if it looks good. I'm fine with an opinionated design as long as it can be turned off

SEO metas should probably always be there even if the option is turned off?

useBreadcrumb in theme-common 👍 the lighter the UI component the better

There's already a component in Infima:

https://infima.dev/docs/components/breadcrumbs

Seems only used on the search page 😅 : https://docusaurus.io/search?q=doc

image

@christopherklint97
Copy link
Contributor

Is it ok if I start working on this? Or will the implementation just be @Josh-Cena useBreadcrumbs?

@Josh-Cena
Copy link
Collaborator Author

@christopherklint97 You can start with useBreadcrumbs + a metadata in each Doc item, and then we can discuss if the UI feature is useful

@slorber
Copy link
Collaborator

slorber commented Dec 17, 2021 •
edited
Loading

  • a metadata in each Doc item

It is probably unnecessary to provide additional metadata here.

We now have a theme-common useDocsSidebar() (in docsUtils.ts), it should be possible to build on top of it a useDocsBreadcrumb(docId).

I'd like to use more context/hooks in the future instead of manipulation props, considering the doc metadata/sidebar should be available in React context wherever those hooks will be called (ie in Doc page components, including custom made components).

@Josh-Cena
Copy link
Collaborator Author

When I say metadata I don't mean props. I mean hooks + <head><meta />

@jodyheavener jodyheavener mentioned this issue Jan 30, 2022
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. status: accepting pr This issue has been accepted, and we are looking for community contributors to implement this
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

feat(docs,theme-classic): docs breadcrumbs jodyheavener/docusaurus
3 participants
@slorber @christopherklint97 @Josh-Cena