JuliaDocs
Generate proper headings instead of merely bold text
For example, in the source docs here there are some headings like # Introduction, # Examples, etc.; but in the rendered page these show up as mere <strong>-ly formatted text.
Ideally the headings in docstrings should be preserved (converted into lower-level headings if needed to fit within the surrounding content). But in case that's not possible, it would be nice to at least add HTML anchors (id= or name= attributes) to the elements corresponding to headings in the source docs, so that they can be directly linked to.
This issue looks like it has been resolved.
-
#generatesh1 -
##generatesh2 - ...
The issue is about headings in docstrings, which we still render with <strong> I believe.
Closing as the current behavior is intended.
See https://github.com/JuliaDocs/Documenter.jl/issues/2308 and https://github.com/JuliaDocs/Documenter.jl/pull/2313
It might still be worth thinking whether semantically it makes more sense to keep the headings as <h*> tags. I suspect the translation to <strong> might have been to satisfy MkDocs.
They don't make sense if they're going to appear deeply nested in a hierarchy. x-ref https://github.com/JuliaDocs/Documenter.jl/issues/1801
One of the advantages of using <h> tags, besides being more semantically accurate, is that they automatically generate anchors that can be linked to (and, if I understand correctly, also searched). I tried to read the linked discussions but failed to understand how the current behavior is preferable to using actual headings. In particular, it seems like #2313 is implementing a search for the headings in markdown to account for the fact that the translation to html is lossy (making them strong/bold instead). Isn't that backwards?
Sorry if I'm missing something obvious.
The problem with <h> headings is that they will render at the wrong sizes. # heading in a docstring should not be an h1 heading on the page. But figuring out the level of nesting is hard. We could add anchors to the strong to make them linkable.
The problem with
<h>headings is that they will render at the wrong sizes.# headingin a docstring should not be anh1heading on the page. But figuring out the level of nesting is hard.
In HTML, the sizes etc. are a styling issue that can be resolved pretty easily -- we just make h* tags that appear in docstrings smaller. And, semantically, I don't think there is a problem having h* "reset" to h1, as long as the docstrings are within their own article or section tags (need to double check exactly which; and also need to double check that this is actually true -- but there should be tools out there that extract the page hierarchy from the HTML, and we should check that it generates a reasonable structure.
- https://web.dev/learn/html/semantic-html
- https://web.dev/learn/html/headings-and-sections#section