-
-
Notifications
You must be signed in to change notification settings - Fork 8.4k
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
Page titles rendered using H1 should have an ID for permanent link #1828
Comments
@endiliey - Thanks for reviewing this bug report. Do you agree with my assessment of this issue? I think the required change for this is straight-forward (set an |
Actually this is happening to v2 site too, but it isn't a problem there because Happening in reactjs.org too, try searching cc @s-pace from algolia for suggestion. |
👋 @endiliey @parvezakkas In order to have the best redirection possible, we highly recommend website owner to add a unique From a DocSearch POV, we would need every headings to have a unique |
Thanks @s-pace for the explanation. @endiliey - Do you agree that all docusaurus generated docusaurus/packages/docusaurus-1.x/lib/core/Doc.js Lines 236 to 249 in b56adb7
|
v2 wont have an id and thats intentional, because the main div body already has id="__docusaurus". We wont put anchor on both v1 and v2, but I think putting id can make sense for v1 to avoid this scrolling bug. Naturally it will be best to slugify the h1 title, but since the beginning of docusaurus, we never slugify it and it could potentially conflict with other headings defined in markdown e.g ---
title: hello
---
## Hello Let's just put id="__docusaurus" here on v1. Its very less likely to see a conflict. Welcoming PR on that So at the end it will be https://docusaurus.io/docs/en/versioning#__docusaurus |
Thanks for the details @endiliey Sorry but I don't get what are the drawbacks of having a unique Having the main div body's Thanks |
Hmmm. Well, to be honest I don't really know why we did so. (had to ask @JoelMarcey as the original author of Docusaurus), but I think its because we actually just don't want the page title as destination anchors. Similar to how the wc3 example don't want https://www.w3.org/TR/html401/struct/links.html It's just like https://reactjs.org/docs/getting-started.html |
P.S Interestingly algolia docs also dont have |
Thanks for the prompt reply and the clarification @endiliey DocSearch Documentation doesn't expose an Table of content is always an edge case and I do agree that these elements should not be part of the search either. This one of the reasons why we do recommend to remove them from the DOM before to parse it at the crawling time. We are going to move our own documentation to docusaurus. I will keep you posted regarding what are the room of improvement in order to provide the best learn-as-you-type experience. |
@s-pace
Sure thing. On another note, we'd be happy to help dogfood docsearch v3 as well when it came out to all of our v2 users. |
@endiliey - Just for clarification, are you saying that v2 of docusaurus does not need an In my opinion, all I spent some time to find a fix using |
Just <h1 id=”__docusaurus” className="postHeaderTitle">{this.props.title}</h1> to fix it in v1
Sent from Mail for Windows 10
|
I don't recall the exact reason for this, but I believe @endiliey is correct. At the time, we were not going to anchor h1s. It's very possible though it was just an artifact of how we developed the project and wasn't a real conscience decision. cc @deltice in case he remembers (Hi 👋) |
@s-pace Love this! :) |
Yup, this wasn't really something that had a lot of deliberate thought put into it, we just didn't have anchors for page titles. |
🐛 Bug Report
Currently in V1 of docusaurus, when the site is generated, it uses the
title
metadata of each markdown files (default/out of the box behaviour). However, this title does not have any id or anchor links unlike all other headings found in the markdown files.This is causing a very weird behaviour when the title of the page matches search results (if algolia search is integrated). Clicking on the link from algolia search result, takes us to the correct page but the header/title of the page is tucked under the site navigation header.
I believe this is happening because the title of the page does not have an "id". When the search query matches the page title, it tries to generate a permanent link to that particular "heading". So, Algolia search result generates a permanent link using the closest parent that has an
id
, which isdocsNav
.The issue is easier to see with an illustration.
Have you read the Contributing Guidelines on issues?
Yes
To Reproduce
version
. The search result might look like this:Expected behavior
Clicking on the search result that matches the page title should have taken me to that page anchored to the page title properly. It should be displayed like this:
Actual Behavior
Clicking on link (https://docusaurus.io/docs/en/versioning#docsNav) from search result takes me to the correct page but the display is skewed. The title is touching the bottom of the top navigation bar:
This does not happen if you try any other anchor links on the page from the right hand side table of content.
Reproducible Demo
(Paste the link to an example repo, including a
siteConfig.js
, and exact instructions to reproduce the issue.)The text was updated successfully, but these errors were encountered: