Add breadcrumb for blog posts

[johnnyreilly]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

Add 2 breadcrumbs to blogs functionality; so blogs would have breadcrumbs in the same way docs have breadcrumbs:

• Blog archive page
  • [BLOG ROOT URL] -> Archive
• Any blog post page
  • [BLOG ROOT URL] -> Archive -> [BLOG POST]

Has this been requested on Canny?

Yes: https://docusaurus.io/feature-requests/p/add-breadcrumb-for-blog-posts

Motivation

I've been on a bit of a mission to improve my Docusaurus blogs SEO. The agency I'm working with suggested adding breadcrumb Structured Data. I've done that implement an invisible breadcrumb using JSON-LD here:

https://johnnyreilly.com/docusaurus-blogs-adding-breadcrumb-structured-data

I'm happy with what I've done, but I'm wondering if it might make sense for Docusaurus to have a breadcrumb in place for blog posts by default. Given that docs already have a breadcrumb (and one that surfaces Structured Data), I'm wondering if it might be useful if blog to as well?

If the answer if "yes", the follow on question becomes: what breadcrumb makes sense? In my head, this makes sense (and it's what I've implemented for my blog):

[BLOG ROOT URL] -> Archive -> [BLOG POST]

API design

I'm unsure what level of configuration would make sense here. Perhaps as simple as having a breadcrumbEnabled: boolean option that defaults to true to allow people to opt out.

It seems likely that we could reuse the existing breadcrumb mechanism (I've had a quick look at the code and it seemed potentially shareable.)

What do you think?

Have you tried building it?

No

Self-service

• [X] I'd be willing to contribute this feature to Docusaurus myself.

[slorber]

[BLOG ROOT URL] -> Archive -> [BLOG POST]

That looks kind of weird to me. It looks related to your usage of Docusaurus but would anyone else use this? I wouldn't turn it on our own blog for example.

Maybe it makes sense for users to have multiple blogs? 🤷‍♂️ The home link seems legit, but the "archive" link looks a bit unnatural to me.

Maybe it's better to post it on our feature request board to see if there's traction/upvotes/feedback from the community.

[johnnyreilly]

The home link seems legit, but the "archive" link looks a bit unnatural to me.

Is it unnatural? If I understand it correctly, all Docusaurus blogs have the archive sat directly under the root of the blog, and all blog links accessible under there. Consider the Docusaurus blog:

https://docusaurus.io/blog

It has the archive under it:

https://docusaurus.io/blog/archive

And underneath that is a link to every Docusaurus blog post; for instance:

https://docusaurus.io/blog/releases/2.3

So a breadcrumb for Docusaurus in this context would seem to be: [BLOG ROOT URL] -> Archive -> [BLOG POST]

Hopefully you see what I mean? So I don't think this particularly related to my usage of Docusaurus; it's how the blog functionality in Docusaurus technically manifests. It's just a question of whether it's made physical or not.

I suppose you could argue that because archive isn't always in the URL, it shouldn't be in the breadcrumb either; but then that's not being applied to docs either I think

Happy to stick it on Canny though. I suspect it's mostly just me that's interested 😉

[johnnyreilly]

Canny: https://docusaurus.io/feature-requests/p/add-breadcrumb-for-blog-posts

[slorber]

docusaurus.io/blog It has the archive under it: docusaurus.io/blog/archive

I don't really agree with that statement 🤪

The blog home is currently a paginated list, and for me the archive is not a "child" of the home. It's just another independent blog page feature, similar to any tag page that also link to the blog post. We can't say there's a parent>child relationship, it's just a different way to access the blog post.

Similarly, we could add later:

• A blog author page. Should the author appear in the breadcrumb? (and what if there are multiple authors 🤷‍♂️ )
• A blog landing page showing the most popular posts, again should it appear in the breadcrumb
• A blog graph view showing an interactive graph with connections between various node types (authors, tags, posts...)

Adding "Archive" in the breadcrumb would mean we bias toward the archive page feature. In the end, there are multiple possible breadcrumb options (or will be once we add more features), and what we have is more of a graph than a tree hierarchy.

Now, having "Home > Post" makes sense to me. We probably need a way to easily navigate back to the blog home. The sidebar "all posts" heading is an option, but the breadcrumb idea is another good one.

[johnnyreilly]

In the end, there are multiple possible breadcrumb options (or will be once we add more features), and what we have is more of a graph than a tree hierarchy.

I think you raise an interesting point. Essentially what you're saying is: which breadcrumb should the physical breadcrumb be? In my post around adding a structured data breadcrumb, I could implement all permutations - so that's what I did based on the Google guidelines:

https://johnnyreilly.com/docusaurus-blogs-adding-breadcrumb-structured-data

Having a physical breadcrumb means rendering a single breadcrumb (or at least I've never seen anyone render multiple). I picked Home -> Archive -> Blog because it means people can get to all possible posts from there.

As a side note, in my SEO travels I've been learning that one of the issues with default Docusaurus from an SEO perspective is that the archive page isn't surfaced into navigation by default. As a consequence, crawlers navigate to older blog posts by crawling the pagination. And that crawling of pagination amounts to reduced SEO juice the more crawling is required. Weird but apparently that's a ranking factor.

Now, having "Home > Post" makes sense to me.

I think this would be good also. Would you be happy with that?

[slorber]

Not sure what you mean by "Physical" 😅 Is this the one that ends up being rendered?

Is it common to render all possible permutations as structured data?

---

The blog breadcrumb should be consistent with docs, and it has a link to the site homepage.

"Site Home > Blog Home > Blog Post" seems appropriate. You can create a PR and we can see if it looks good in practice.

---

the archive page isn't surfaced into navigation by default

Yes this is a problem. The only way for Google to find is by submitting the sitemaps manually. In your case it shouldn't change anything because you have a link to the archive page in your navbar. But it is indeed a SEO problem for many other Docusaurus sites.

My idea was to introduce the concept of blog sidebar items, and allow us to add an item of type "archiveLink" so that we can access the archive page from the bottom of the blog sidebar:

That's probably also worth adding this right now, even if the blog sidebar items thing is not yet ready and would require a little breaking change (because we now need an item of type "postList" or something)

[johnnyreilly]

Not sure what you mean by "Physical" 😅 Is this the one that ends up being rendered?

Yup!

Is it common to render all possible permutations as structured data?

I don't know - I did it because it was possible. I'm not that sure it's useful.

My idea was to introduce the concept of blog sidebar items, and allow us to add an item of type "archiveLink" so that we can access the archive page from the bottom of the blog sidebar:

sounds good. Is that different from the "last X posts" that currently exists? Or is the idea that existing component might slot into a new blog sidebar alongside say an archiveLink?

[slorber]

Is that different from the "last X posts" that currently exists? Or is the idea that existing component might slot into a new blog sidebar alongside say an archiveLink?

Not sure what you mean.

For now the sidebar is a monolithic component, but I'd like it to become more flexible like the docs sidebar, the navbar, and allow users to create "custom types". IE if you want to add a "tags cloud" item to the blog sidebar you could easily without swizzling.

[johnnyreilly]

this is what I meant by last X posts. I think you and I are talking about the same thing. (the sidebar component)

[slorber]

My idea is to have something flexible, maybe like this:

blogSidebarItems: [
  {type: "xLastPosts", limit: 10}, 
  {type: "link", to:"/archive", label: "See all posts"},
  {type: "popularTags", limit: 5}, 
  {type: "popularAuthors", limit: 5}, 
]

[johnnyreilly]

Oh nice!