documentation
documentation copied to clipboard
Qiskit
Add anchor tags to subheaders so that anchors work with translations
When there is a lull, go through all docs and add anchor tags (e.g., <span id="local"></span>) to all subheaders so that anchor links to those headers won't break if header names change.
Can you also please update the contributing guide to tell contributors they should add these tags when they add new content?
Although note that it's not safe to use the same ID name as the header itself because we already convert the header to an ID, like My Header becomes my-header. So I'm not sure what new name we'd use for all these spans?
Can you also please update the contributing guide
This will be easier when adding the markdown guide: https://github.com/Qiskit/documentation/issues/367
I think this idea actually will become very important when we add translations, as explained in https://github.com/Qiskit/documentation/issues/7.
But we still need to figure out what naming scheme to use for the manually created IDs.
@Eric-Arellano I'm curious why we can't use the same name in the anchor tags as the current header names -- will something break if we assign a tag like my-header to My Header (maybe because the my-header tag has already been autogenerated for that same header)? Or is it just that the anchor tag name will go out of date if the header name changes?
I'm curious why we can't use the same name in the anchor tags as the current header names -- will something break if we assign a tag like my-header to My Header (maybe because the my-header tag has already been autogenerated for that same header)?
In English, the header is # My header. In Spanish, that will be translated via the translations team in Crowdin.com to be # Mi Cabecera. So, when the anchor is generated by the documentation app, it will be #mi-cabecera on the Spanish version of the page and #my-header will be undefined.
We cannot expect translators to know when translating URLs how to translate the anchor because the header translation will have happened elsewhere in the project and the anchor URL is only a reference to that other translation. For example, the URL ./my_page#header: that gets defined on my_page.mdx, but the link to it might be in some_other_page.mdx. So it's not realistic for translators to handle this nuance. Generally, we don't want translators touching any URLs.
The application cannot handle this automatically because it does not map the English pages to the translated pages. We couldn't do that also because translations will have some lag time with the English, like English will be more up-to-date and the content might change.
So, the only viable solution I've thought of is banning using headers for anchors and requiring using <span>. That's viable technology wise and we can adjust the link checker, but it's more friction for the writing team. It's also not clear to me how we determine what the ID should be for the span since it can't be the same as the header, per HTML standards. I want to talk to @javabster and y'all about your thoughts on this all and the prioritization.
When we get round to this, we should automate it and not do it by hand.
Closing in favor of a closed source issue tracking doing this automatically. I don't think it's necessary for content authors to do this even for English because our link checker will catch the problem.