Use a better scale in headings typhography

[lud]

Hello,

Sometimes I find that document structure is hard to read, especially in markdown guides. Here is an example:

---

---

• Plug integration is an H2
• Plug options is an H3
• Using a module is an H4

To me there is too little difference between H2 and H3 levels, which make section look like they are unrelated. Fortunately the different whitespace margin helps.

Also, the H4 level feels way too small, I feel like it should be at least as high as the copy font. (In my opinion H6 should be paragraph size and other headings larger).

What do you think about this?

Thank you :)

[DavidOliver]

Agreed. I'll look to better differentiate the levels of heading.

[lud]

I don't know if you are familiar with typography scales. It can help to quickly chose sizes that fit together.

[DavidOliver]

I'm aware of the concept but hadn't come across that particular tool, which looks great. Thanks.

If heading levels 1-6 all need to be appreciably distinct from their nearest neighbours, it can be hard to depend on size alone without level 1 being awkwardly large in the context of documentation pages, so I expect I'll also be experimenting with devices such as horizontal rules.

[josevalim]

In our case, I think we can adjust the sizes assuming folks will use h1 to h4. H5/H6 is rarely used and we can use font weight or similar for those.

[lud]

The Major Third scale is not too big on H1 but yes, H5 could be just bold and h6 normal with a margin top.

[DavidOliver]

It turns out that the difference in size between our H2 and H3 was already greater than that of the sizes which typescale.net suggests for the same levels with the Major Third scale.

What do you think of the below (current/suggested):

The H2 is at 1.8rem (and so closer to the H1 size of 2rem, which I don't think matters as the only H1 should be at the very top, once) with a horizontal rule. Sizes of H2-H4 (all three shown here) have increased.

The horizontal rule helps to separate the main sections:

[lud]

Hi!

I'm not a fan of the hr between the title and its content but that's personal preference. Or maybe it should be thin as in the Elixir/Erlang tabs. And it's too far away from the heading (sorry I can be so annoying with typography and everyone has their valid opinion). Anyway, it helps to see the structure indeed.

Anyway, the sizes are definitively better like this in my opinion 👍 Whatever you chose as a style with those sizes will be an improvement.

Thank you!

[josevalim]

Yeah, not a fan of the hras well :(

[DavidOliver]

No problem. :) Here it is without the rule for H2 and with a little additional spacing above H3 and H4:

[lud]

Hello, sorry for the delay!

I think it's nice :)

If you want to iterate more I'd suggest to reduce the spacing below the headings until you find that sweet spot. Like "Features H2" seems too far from the text. But I guess this is extremely subjective.

I guess I'll let you guys chose whatever you like the most. It's already much better! <3

[DavidOliver]

Yes, I wasn't entirely sure about the space under the headings. All headings now have only .5em margin-bottom instead of the 1em in the above screenshot. This means that, at least in the case of H2, the 1em margin-top of the (1rem) following paragraph is defining the space. (Margins are collapsing.)

[lud]

I guess you could only define margin bottom for p, ul, pre, etc ?

edit: Wait, how comes the h3 is now closer, it it has margin-bottom: .5em and the p has margin-top: 1em. Both spaces under h2 and h3 should be unchanged and be 1em no?

Ah ! I guess because of em instead of rem it depends on the heading style :D

I'm sorry it's been a while I haven't do some CSS typography. I remember I just used rem everywhere.

Like this:

/* set the line height to 1.5 */
html { font-size: 16px; line-height: 1.5 }

/* set the margin bottom to half a line. 1.5rem would be a full line */
p, ul, pre, h2, h3 { margin: 0 0 .75rem }

If you want I can give it a try, but I'm afraid the API reference docs may suffer from those kind of changes!

[DavidOliver]

Yes, that's right. :) The existing margin styles use em, and this way of doing it can make sense if one wants the margin to be relative to the heading's font size.

I wouldn't necessarily be opposed to trying a reduction, but the margin-top of 1em on the main/body text doesn't seem overly large to me. Changing this for all paragraphs in the .inner-content might have knock-on effects, so I'm inclined to leave that as-is unless you and @josevalim feel strongly that it needs to be reduced.

(I will need to check for knock-on effects of changing the heading margins, too, but I'll wait until we're agreed on the spacing before doing so, as well as making sure that H4-H6 look okay.)

[josevalim]

@DavidOliver can you please send a PR with your changes so I can give them a try locally? I am not necessarily a fan of the margins, I'd prefer to stickl with size only, but maybe it is all fine once I load it locally instead of using screenshots :)