inconsistent h levels

[chikamichi]

I noticed the h levels are inconsistent. Main title is h1, then most pages (if not all) jump straight to h3 and h4 for section and sub-section titles.

I guess @jzimdars styled the DOM as it was proposed. I'm wondering whether we should transfer h3 styles to h2, h4 to h3's etc. and fix markdown files, though.

[jzimdars]

You're right. Doing the design on spec meant it wasn't feasible to re-think the mark-up of all the pages—I worked with what was already there. There are other similar clean-up tasks that need doing, too:

• Remove the template images related to the old design from the repo
• Remove CSS classes related to the old design from templates

I can try to do those as time permits.

As for the heading issue, the easy route would be to change the page titles from h1 to h2. That would require the least amount of markdown changes. There are only a few outliers that use h2 instead of h3 right now (/security for one). That way you'd have:

h1. Ruby
h2. [ Page title ]
h3., h4. [ ... markdown headings ... ]

This would also appeal to purists who prefer a single h1 per document. I personally don't think that's necessary but this is the easiest route to consistent leveling. And the only CSS change would be to style the #content-wrapper > h2.

[chikamichi]

Ok, I like this way around. I'll do that "as time permits" ;)

[jzimdars]

FWIW, I took a stab at this over the weekend (https://gist.github.com/jzimdars/70d55fde7ae85c02002f) and I was't happy with the result. From the point of view of a writer, it felt unintuitive and unnecessarily limiting that the first heading you could use in a MD file was h3. I also noticed that my proposed work-around didn't save as much effort as I anticipated. Many of the news releases correctly start with h2 — it's mostly just a few content pages that jump to h3. So, the biggest problem is that headings haven't been used consistently for a long time and multiplied by localizations it's a fair amount of work to pore over everything to enforce consistency.

In the end it's a minor issue and even HTML outliners aren't tripped up by this:
http://gsnedders.html5.org/outliner/process.py?url=https%3A%2F%2Fwww.ruby-lang.org%2Fen%2Flibraries%2F

So I don't feel strongly either way, just wanted to share this impression after working on it.