Add a breadcrumb to pages

[patricklafrance]

Hello!

I have a feature request :) I would like to have a breadcrumb in the pages as a supplementary form of navigation to help with nested pages.

Ex: References >Registration > registerLocalModules

[geoffreymcgill]

Thanks for the breadcrumb feature request.

This is functionality that has been on our list for a long time but just never implemented. I have bumped up the list but I don't have a time frame for when we could implement. We will certainly keep this thread updated with our progress.

[geoffreymcgill]

Initial draft of the breadcrumb navigation:

Or with just Home instead of an icon:

Let me know what you think.

[patricklafrance]

Good question, I think the first one with the icon but I honestly like both.

[patricklafrance]

The WAI-ARIA breadcrum pattern is using the actual name of the home page rather than "Home" but there's only an example for the component no specification so it's hard to say why.

I think I prefer an Icon or "Home" to the actual name of the home page.

[geoffreymcgill]

It will be possible to configure with text or an icon.

It is possible to make the home Icon version WAI-ARIA compliant by including the Home text in a hidden element, such as:

<span class="hidden">Home</span>

The HTML we are generating for the Breadcrumb is WAI-ARIA compliant.

The following screen recordings demonstrate functional mockups for both scenarios:

With Icon

https://github.com/retypeapp/retype/assets/62210/e392344d-daed-4e54-bccd-913c8053da73

Without Icon

https://github.com/retypeapp/retype/assets/62210/182b1bea-d424-42d9-8dd3-37470ca76cfe

In both screen recordings above, the References node does not have a index/default page, so it is not directly linkable. Retype would not build a link to the References page.

[geoffreymcgill]

Our current plan is to implement the following breadcrumb project options:

breadcrumb:
  home: Home # default, locale specific
  separator: ":icon-chevron-right:" # default

All of the following scenarios would be possible:

Light/Day mode

Dark/Night mode

[geoffreymcgill]

It will also be possible to use an .svg image as a separator, although the .svg file will need to be configured with the following attributes and size:

<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18" fill="currentColor" aria-hidden="true">

Light/Day mode

Dark/Night mode

[geoffreymcgill]

Just thought of another scenario that would be supported. Use any .svg as the home icon. In the following sample, the Home 6 icon from iconmonstr was used.

breadcrumb:
  home: /static/home.svg

Light/Day mode

Dark/Night mode

Again, the .svg would need to be exported and/or configured with the following attributes and size:

<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18" fill="currentColor" aria-hidden="true">

[patricklafrance]

Amazing! Thank you 🙏🏻

[patricklafrance]

I was wondering if the "Home" link is that useful? It keeps bothering me as I find it redundant and I don't feel like it brings much value to the reader.

I haven't said anything yet because every website I tried seems to include an "Home" link to their breadcrumb.

This morning, I stumbled upon the NextJs documentation which doesn't included an "Home" link in their breadcrumb and I personally likes it a lot.

It's shorter and less redundant.

What do you think?

[geoffreymcgill]

What do you think?

What would be the breadcrumb trail for the page https://retype.com/roadmap/?

[patricklafrance]

I am not sure that a root page would need a breadcumb.

At least, this is how the Nextjs documentation is approaching this.

[geoffreymcgill]

For Retype projects, the home page of the documentation would not get a breadcrumb, same as the Nextjs screen capture you shared.

The scenario that is problematic is what should happen to other pages at the root level (i.e. not the root page)?

Pages at the root level can either:

1. Include a home link: Home > Roadmap
2. Do not render a breadcrumb (creates an inconsistent experience, not ideal)
3. Use only the current page name: Roadmap (far from ideal)

On retype.com, once the breadcrumb is available, I would remove the Home link in the top navigation, then users could use the breadcrumb Home link to easily navigate back home. That also nicely simplifies the top nav.

If all the pages of your project are in sub-folders, then eliminating the Home link could be an option. We could build this into the breadcrumb config as an option. Maybe just home: false would be a simple enough option. But, any root pages in the project would not get a breadcrumb if home: false.

[patricklafrance]

To keep using the NextJs documentation example, other root pages also don't get a breadcrumb:

My natural thinking would be that a breadcrumb trail is useful to keep track of where a page is in a hierarchy. So if a page is at the root of the hierarchy, does adding a breadcrumb trail helps the reader? Maybe the answer is yes as it quickly helps the read understand that the page is indeed at the root of the hierarchy. I am not sure, I don't have a strong opinion on this.

On retype.com, once the breadcrumb is available, I would remove the Home link in the top navigation, then users could use the breadcrumb Home link to easily navigate back home. That also nicely simplifies the top nav.

Agreed, but that also requires the user to navigate to the top of the page to navigate to the home page. It's not exactly the same experience.

We could build this into the breadcrumb config as an option. Maybe just home: false would be a simple enough option. But, any root pages in the project would not get a breadcrumb if home: false.

Could that configuration be at a page level rather than at the project level? I could picture this in a page metadata:

breadcrumb: false

or if you prefer to be future-proof:

breadcrumb:
    - visible/include/display

[patricklafrance]

To be clear, I love the current implementation and would use it. I am only sharing my findings and brainstorming options.

[geoffreymcgill]

Agreed, but that also requires the user to navigate to the top of the page to navigate to the home page. It's not exactly the same experience.

The project branding, top-left logo or project name, is also a home link, and always available, and is standard paradigm for website UX.

For reference, here are two screen captures demonstrating with the top-nav Home link and without:

 

 

 

Could that configuration be at a page level rather than at the project level?

The current plan is to include the breadcrumb config as both a Project and Page level config option. Setting at the Project level (retype.yml) creates a default configuration for the entire project, which can then be overridden at the Page and Folder levels.

Setting the following on a page would disable the breadcrumb for that page:

breadcrumb:
  enabled: false

We could also likely build in the option for breadcrumb: false at both the Project and Page level.

breadcrumb: false

I'm still thinking home: false would be a useful config option to have:

breadcrumb:
  home: false # No Home link in the breadcrumb trail

The above could be set at either the Project, Folder, or Page level.

I don't have a strong opinion on this.

I don't have a strong opinion either. The ideal scenario is to provide enough flexibility with the app so that project authors can decide what is best for their project.

Hope this helps.

[patricklafrance]

Sounds good, thank you for the clarification 👍🏻

[geoffreymcgill]

Retype v3.3 has been released and includes the new breadcrumb navigation.

See the retype.com website for a working example of the breadcrumb navigation, as well as the breadcrumb project and page config documentation.

I believe all the features proposed in this thread are currently supported. More breadcrumb documentation is coming soon. I apologize for the docs being thin on details right at the moment.

Huge thanks to @patricklafrance for sponsoring the development of this feature!

Hope this helps.

[patricklafrance]

@geoffreymcgill There seems to be an alignment issue when there is no "Home" icon:

[geoffreymcgill]

There seems to be an alignment issue when there is no "Home" icon:

Can you share your breadcrumb config? Also, which web browser and OS are you testing with?

[patricklafrance]

@geoffreymcgill sorry for the false alarm, it's our custom CSS 😅

We added custom CSS for the ul/ol lists in the markdown content but it also affect the breadcrumb:

    .docs-markdown ol, .docs-markdown ul {
        padding-left: 1rem !important;
    }

[patricklafrance]

I believe my current website is an edge case. My home page is the default page of the "Getting Started" section (folder):

root
   /getting-started
       default.md <------ My home page
       create-host.md
       etc...

By default, I get the following breadcrumb for my home page ("Getting Started")

Which is 2 links refering to the same page (the home page).

Therefore, I disabled the breadcrumb for the root/getting-started/default.md page with

---
breadcrumb: false
---

As expected, I don't have a breadcrumb anymore for the root/getting-started/default.md page. But I've also lost the breadcrumb for the root/getting-started/create-host.md page as well (which is expected according to the documentation)

To get the breadcrumb back for the root/getting-started/create-host.md page, I enabled the breadcrumb feature specifically for that page with:

---
breadcrumb: true
---

Which also works as expected, but now my breadcrumb for the root/getting-started/create-host.md page contains 2 parts (Home and Getting Started) that are again refering to the same page (the home page):

I am not sure what would be the expected behavior here:

• Should the "Home" link not be rendered?
• Should the "Getting Started" link not be rendered?
• Should I disabled the breadcrumb feature for the whole "Getting Started" section?
• Is my website structure too messed up?

We are not expecting to add a proper welcome page for our small documentation websites because we don't see much value into it at the moment, (we expect to have 15-20 documentation websites in the coming year) but maybe we should?

Let me know what you think 🙏🏻

[geoffreymcgill]

Thanks for the report. I'll try and reproduce this scenario and see what we can do to support.

[geoffreymcgill]

Can you share your retype.yml? feel free to remove link, footer, etc configs that would not relevant to reproducing this scenario.

Do you have any .md files in the root of the project? I'm just not sure how to reproduce "My home page is the default page of the "Getting Started" section", where the :icon-home: would be the same link as the Getting started page?

[patricklafrance]

@geoffreymcgill our code is open-source, you can find the repository here :)

I haven't commit anything related to the breadcrumb feature yet thought.

[patricklafrance]

But basically the trick that I used is that the Retype default.md page redirect to the getting-started/default.md page.

Content of the default.md page:

---
redirect: getting-started
visibility: hidden
---

[geoffreymcgill]

How about setting home: false in your retype.yml?

breadcrumb:
  home: false

[patricklafrance]

I was hoping to have the home link in the breadcrumb for my other pages (and to get a consistant breadcrumb experience accross all our documentation websites) but yes that could be an option:

[patricklafrance]

Yeah maybe it's for the best. As mentionned previously, I am not sure what would even be the ideal behavior for that website. OK, I'll remove the home link for all our sites.

[geoffreymcgill]

We could add another project config that would allow for a custom link on the home node.

I'm not sure what to call it though, maybe just link.

Then I think the following config would support your scenario a little cleaner:

breadcrumb:
  home: ":icon-home:"
  link: /getting-started/default.md

but, unless you are linking to an external location, this doesn't really get you anything new than what can already be achieved with the existing config options. The pages within /getting-started would still kinda have two links to the /getting-started landing page:

Without a root landing page, a compromise with the breadcrumb in your project might be required.

[patricklafrance]

Indeed, I am not sure that would do it either.

For now the best option seems to remove the Home link, which is fine. I am already used to it :)