Fix h1 headers in the Table of Contents
#13
Comments
|
Hmm I think there are a few things to tease apart here... First, we can/should definitely clean up some of the titles/H1s used in the farmOS docs. A lot of the decisions made there were workarounds for the way Mkdocs and the Material theme ended up putting things together - but they were less than ideal. You and I can walk through these together and decide what will work best in the new system. I like the idea of using front matter for defining the page title (and other meta data). So maybe we just need to add front matter (along with cleaning up existing farmOS doc titles/headings), and refactor TOC code to use front matter instead of headings? Separately, and pardon my old school thinking, but I think each page should have a single H1 semantic heading. I'm curious to understand why https://gracious-brattain-bdd606.netlify.app/docs/js/ uses multiple (eg: "Overview", "Quick start", "Next steps" all at the same highest level). I know that HTML5 has made the "one H1 tag" rule less strict, but my understanding is that it should still be the "primary heading for a single document", and that while multiple H1 tags can be used on a page, this should only be done when the sections represent separate documents (and are wrapped in In either case, that is maybe a separate discussion. It seems like front matter would solve the TOC issue, right? |
|
Oh wait sorry - I mixed things up a bit... the "TOC" in question is the one on the right (not on the left). So front matter can't be used for that. |
|
Ah, ok, I think you and MDN have convinced me. I guess I just took to heart the kind of document structure I learned in school, from whatever writing style guide it was based on. The idea there was that every heading marks a section or subsection, and a section is only a section if there is more than one section of equal level within the parent section, or within the document in the case of top-level sections. Its designation as a "section" is kinda meaningless otherwise. So if you wind up with only one That logic still makes a heck of a lot more sense to me, subjectively at least, but I'm willing to yield to the convention if the web still does it differently. I thought I read somewhere that convention got phased out with the advent of HTML5, but I'm not finding that now. I can downgrade all my |
Yea I feel ya! That does make intuitive sense to me too - in the context of prose at least. :-)
Sounds good - that seems like the easiest way forward here, and will be consistent with other markdown docs (both farmOS's and others that may be included later). I'd still love to go through the farmOS titles/headings together with you as the front matter stuff comes together! It would be good to make sure we're as semantically-correct as possible. The best kind of correct! :-P |
So, I "downgraded" those headings in the farmOS.js docs like I said (farmOS/farmOS.js@04e720c), and I think that pretty much resolves it? I could still tweak the logic a bit for that ToC, but I don't know if that makes sense at the moment, if we're just going to enforce this convention for now. Perhaps it's something for @paul121 to be aware of if he wishes to go ahead and add farmOS.py, as we discussed in #17. It may be good to reevaluate options when we do integrate Front Matter headers. I'll open an issue for that now, while I'm thinking of it, and link to this discussion. Closing this for now though. |
As I first pointed out in #8 (comment), the Table of Contents for the farmOS.js docs are omitting all but the first
h1heading for each page. This is attributable to how thetableOfContentsHTML is being altered in the docs template:https://github.com/farmOS/farmos.org-EXPERIMENTAL/blob/dde4781adb1f2ff2385b60ab918988d410e9f740/src/templates/docs-page.js#L38-L53
I did this to accomodate a quirk of how the farmOS docs use
h1/#more as a title than a proper heading. I knew at the time it would lead to such issues, but I used this quick fix so we could have a broader discussion when the time came.Well, the time has come. @mstenta, what are your thoughts?
IMO, it's better to use
h1as a true, semantic heading. Markdown doesn't have syntax for titles, but now that we're using Gatsby, we can use Frontmatter for these kinds of details. I see Frontmatter as a good analog to the<head>tag, which is where the title really belongs, rather embedding it in the markup.The text was updated successfully, but these errors were encountered: