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

Add breadcrumbs with links to parent pages in the article header #1137

Closed
choldgraf opened this issue Jan 26, 2023 · 4 comments · Fixed by #1142
Closed

Add breadcrumbs with links to parent pages in the article header #1137

choldgraf opened this issue Jan 26, 2023 · 4 comments · Fixed by #1142

Comments

@choldgraf
Copy link
Collaborator

Many websites put "breadcrumbs" at the top of the page so that you can quickly see what parent pages are above you, and click through to them. For example:

The RTD theme:

image

The MDN docs:

image

What do folks think about using our article-header area to include breadcrumbs for each page? If we were worried about horizontal space, then we could restrict it to 2 parent pages, or limit the number of characters per header title or something.

@drammock
Copy link
Collaborator

I'm open to supporting this as long as it's optional / can be turned off in config. Are the intermediate levels in a breadcrumb guaranteed to exist though? (will there always be an index.html in every subfolder in _build/html/?) Off the top of my head, I'm not sure, but my guess is that it is not guaranteed by Sphinx.

@choldgraf
Copy link
Collaborator Author

I think the way you'd do it is by looping through a page's parent documents and using their titles + hrefs...those always do need to exist. So the folder structure in the filesystem wouldn't matter as much as the toctree structure of the documents

@trallard
Copy link
Collaborator

+1 on this one as this would help with navigation, especially if adding #1072

We should also consider how many levels will be displayed in the breadcrumbs or/and make this customisable. I think if there is a doc nested a few levels this might take too much space or would not fit the width at all

@choldgraf
Copy link
Collaborator Author

Fwiw, it looks very simple to implement. It is just this couple of lines in the RTD theme (assuming that the "parents" variable is built into sphinx)

https://github.com/readthedocs/sphinx_rtd_theme/blob/6444ca893043d8a0ca704474f7cf7d5a148f6767/sphinx_rtd_theme/breadcrumbs.html#L24

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants