facebook / facebook/docusaurus

Add Breadcrumb customization options

Open
#6,953 18 comments 10 reactions 0 assignees View on GitHub
feature
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

### Have you read the Contributing Guidelines on issues?

- [X] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).

### Prerequisites

- [X] I'm using the latest version of Docusaurus.
- [X] I have tried the `npm run clear` or `yarn clear` command.
- [X] I have tried `rm -rf node_modules yarn.lock package-lock.json` and re-installing packages.
- [X] I have tried creating a repro with https://new.docusaurus.io.
- [X] I have read the console error message carefully (if applicable).

### Description

If you have the docs module configured where the structure matches the category index convention as mentioned for [autogenerated sidebars](https://docusaurus.io/docs/sidebar/autogenerated), for example you have the following pages and URLs:

/docs/docs.md -> /docs/
/docs/item1.md -> /docs/item1
/docs/cat1/cat1.md -> /docs/cat1
/docs/cat1/sub1.md -> /docs/cat1/sub1
/docs/cat1/sub2.md -> /docs/cat1/sub2

it seems like in this usage, the breadcrumbs should match the URL structure and show all the links contained in the full URL. However, if you are on the sub2.md page, the bread crumbs goes from "/" to "/docs/cat1" and skip over the "/docs" url link:

"/" -> "/docs/cat1" -> "/docs/cat1/sub2"

I think the breadcrumb should either be

"/docs" -> "/docs/cat1" -> "/docs/cat1/sub2"
or
"/" -> "/docs" -> "/docs/cat1" -> "/docs/cat1/sub2"

Basically, the first idea would be to have the breadcrumbs "home" to go to "/docs" instead of "/" (when /docs is a valid URL). I think this makes sense since the breadcrumbs are specific to the docs module, so it isn't clear that "home" should go to the website home instead of the docs home. Maybe the way to implement this is for a parameter to set the breadcrumb home URL.

Another option would to (maybe optionally) add the "/docs" to the breadcrumb structure.

### Reproducible demo

https://docusaurus.io/docs/sidebar/autogenerated

### Steps to reproduce

Create structure like shown in https://docusaurus.io/docs/sidebar/autogenerated and enable breadcrumbs.

### Expected behavior

breakcrumbs would look like

"/docs" -> "/docs/cat1" -> "/docs/cat1/sub2"

or

"/" -> "/docs" -> "/docs/cat1" -> "/docs/cat1/sub2"

### Actual behavior

breadcrumbs are

"/" -> "/docs/cat1" -> "/docs/cat1/sub2"

### Your environment

Tested on beta17

### Self-service

- [ ] I'd be willing to fix this bug myself.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.