36

Edit: I have changed the answer in question to use ### instead of ## now.


See this answer of mine: https://stackoverflow.com/a/20820086/538216

The asker of the question keeps editing my post to remove the headers. His original reason for the edit:

At Stackexchange, no one can hear you shout. So I fixed the formatting (and the broken code-block while I was at it).

I have three problems with this:

  1. He changed my brace formatting so the curly brace goes on the newline. Unacceptable!
  2. My formatting wasn't broken... until he broke it.
  3. I don't think my use of header Markdown is inappropriate.

This question is really about headers, because points 1 and 2 are funny more than anything.

Is my use of header Markdown an acceptable one? If not, enlighten me as to why it is not.

11
  • 7
    In my opinion, those headers are too much. The add more noise than content. Bolding would be enough.
    – Oded
    Dec 31 '13 at 16:50
  • 5
    It is rather attention-grabbing. I wouldn't edit your answer over it, but consider at least using ### instead of ## headers. Dec 31 '13 at 16:55
  • 2
    @Oded not all of us answer questions, which require 2-3 short paragraphs.
    – teresko
    Dec 31 '13 at 17:01
  • 5
    I don't care much about headings, but putting the curly brace on the next line definitely borders on offensive ^^
    – NikiC
    Dec 31 '13 at 17:12
  • 3
    I find it quite rude to the other answers TBH. It certainly makes yours stand out more and I agree with the sentiments that it is "shouting" and "attention grabbing" Dec 31 '13 at 17:56
  • @MartinSmith Keep in mind they all had 2 day head start or more; even still I think it is neither rude nor shouting but perhaps attention-grabbing, but that rather is the point of headers, is it not? Dec 31 '13 at 18:04
  • 5
    @LeviMorrison - But if everyone does it then you end up in an arms race of inappropriate formatting. It is much better for people to exercise restraint IMO. Your answer would be fine (IMO again) with ### rather than ##. Dec 31 '13 at 18:05
  • 3
    @MartinSmith I don't think it's inappropriate, but I did do the right thing and asked about my behavior here in meta even though I think I'm not in the wrong. The only reason I haven't changed it down to ### now is because I want to preserve formatting for this meta question. Dec 31 '13 at 18:07
  • 3
    @LeviMorrison - Yes, good. But you asked for opinions I gave you mine! Dec 31 '13 at 18:08
  • As you don't have the rep to see deleted answers here: the editor didn't know they were removing a syntax highlighting hint when they removed the <!-- language: lang-php -->...
    – Arjan
    Jan 1 '14 at 12:32
  • If somebody thinks that headers shouldn't be used, he must read some of BalusC posts. They are useful for sure, but we have to use them with moderation. I also think that h1 is too big and in most of the cases it should be avoided. Jan 7 '16 at 8:11
40

I use headings in answers all the time. These are the rules I (try) to follow:

  • Avoid h1 headers (single hash prefix) unless you REALLY need three levels of headings within your answer. You almost never do need this. Remember, there's already one h1 at the top of the page - it's the title of the question!

  • Don't use headers at all unless there are at least a few paragraphs between them. In many cases, what you really want is... A list!

  • Do use headers when there are multiple, discrete topics being explored in a single answer. I've seen people write hard-to-read walls of text in cases where just a few clear, descriptive headers would make it much easier to recognize the presence of individual sections within the text. Use headers to give an at-a-glance view of the structure of your answer, so that folks can skip to (or skip back to) the relevant section quickly.

3
  • 3
    +1/-1/+1 for your three points. Bullet points are reminiscent of PowerPoint slides thrown together at the last minute. Great for lists/phrases, awful for paragraphs/sentences.
    – jmac
    Jan 14 '14 at 23:48
  • 1
    Why avoid H1 headers? If I want 2 levels only, those levels are H1 and H2, not H2 and H3. Why H2 and H3 and not H5 and H6? It's SO's fault to make the markdown # header the same size as the question title. Oct 7 at 16:40
  • 7
    @ThomasWeller This answer is a bit out-of-date as we now allow six levels of headers when at the time of writing we only allowed three. That said, I'd still argue that avoiding H1 is a valid choice - in fact, I never use it myself. Yes, we could change the system but, failing that, this answer is still valid.
    – Catija StaffMod
    Oct 7 at 16:45
27

If the SE devs didn't want us to use Markdown headers at all, they'd just disable the feature.

Then again, just because something is technically allowed doesn't meant it's always a good idea.

Certainly, if you feel your post actually benefits from the structure provided by multiple levels of headings, you should use them. However, using large headings just to grab attention can be seen as distracting and obnoxious behavior.

In particular, if your post needs only one type of headings, please consider using the smallest kind that still stand out from body text (typically ###), or even just bold or italic text.

I wouldn't personally edit you post merely over such a minor issue as the difference between second and third level headings, but neither do the oversized (and seemingly gratuitous) headings make me super-inclined to vote it up, either.

1
  • I agree with the practice you've described and would expand it: start small, work up. If the answer (or question) is detailed, and subject to continuous rolling edits (which some of the greatest answers on SE are) gradually sectioning larger fragments of a post from h3 through h1 makes a lot of sense.
    – Dan Lugg
    Dec 31 '13 at 17:20
18

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Bold text

Text


I think SO just has a styling issue here: Heading 3 (###) is just bold text with a different font (which actually makes it appear smaller than plain bold text). Heading 2 (##) on the other hand is already much larger and has a weird over-large margin below it. Heading 1 (#) again is only a bit larger.

Suggestion: Fix margin of h2, make h3 larger. Or h2 and h1 smaller.

7
  • 4
    just wanted to write the same ^^
    – hakre
    Dec 31 '13 at 17:31
  • 3
    What are you viewing this with? I see H3 clearly larger than bold, maybe 20% or so. Same with H1 v H2. Agree with the weird margins, though. Chrome latest, Ubuntu 13.10.
    – Geobits
    Jan 2 '14 at 1:35
  • @GenericHolidayName I'm using FF/Chrome on Win7.
    – NikiC
    Jan 2 '14 at 11:42
  • I can confirm that on Chrome latest on Mac OS X 10.9 that h3 looks smaller than the bold. Jan 15 '14 at 6:09
  • They work fine for me: H1 > H2 > H3 > B. I tested it in Chrome 47, Firefox 39, IE 11. Jan 7 '16 at 8:19
  • 3
    @engineer This answer is two years old.
    – NikiC
    Jan 7 '16 at 10:19
  • 1
    @MateenUlhaq If this answer is going to show <H4> and <H5>, is there a reason not to show <H6>? Note that this entire answer is substantially out of date in that the CSS has changed significantly since it was written (multiple times), which really makes it no longer applicable.
    – Makyen
    Oct 9 at 6:59
7

Personally, I would rather see fewer headers in answers. It's becoming quite a trend on The Workplace with

Executive Summary

blah blah

Background Reasoning

more stuff

and so on for several screens. I generally feel if your answer is so long and complex that it needs to be broken into sections, the question is too broad or your answer is too long or both. I would not miss this markup if it was removed.

7
  • 7
    There's no such thing as "too long", just "too chatty". If all information in your answer is relevant, I wouldn't say the answer needs shortening anyways Dec 31 '13 at 20:37
  • 2
    a question that cannot be answered with less than 4 or 5 pages is too broad... Dec 31 '13 at 20:39
  • This seems to be primarily directed at me (since virtually all my answers are formatted that way). I prefer this style because it makes sure that my thoughts are collected and that I cover the various bases. If I can't summarize my thoughts in a single short blurb, then my answer isn't focused. If I can't identify the main concepts to justify that answer, then I haven't thought it through. Breaking out the headers helps me organize my thoughts, and allows the reader to follow the same thought process that I went through to answer. And anyway, is 1,000 words really 'too long'?
    – jmac
    Jan 14 '14 at 23:45
  • @jmac I hadn't noticed whether it was one user or not. It seems to be the accepted style on w.se. I just don't like it. I'm not in charge of style, but if I were, I think omitting the Executive Summary, the TL;DR etc would help, and I would introduce the sections not with a # header but with a single short bolded sentence at the start of each paragraph. I find the headers too different from the rest. BUT clearly the rest of the site disagrees, if all those answers are by you, because they're pretty much always the top answer on every question, so keep doing what you're doing, it's working! Jan 15 '14 at 1:06
  • @Kate, taking a quick peek, it is primarily me. I have gotten suggestions to drop it down from # to ## which was done early summer or so, maybe I'll consider dropping down from ## to ### or even a bolded sentence, but I think that doesn't separate things as well. Personally when I'm reading an answer, I want someone to tell me the answer first, and then explain why, which is why I include the executive summary, but I understand not everyone is as enamored with that as me. It does seem to serve me well though.
    – jmac
    Jan 15 '14 at 1:12
  • @jmac I like leading with the short pithy answer. I just don't like labelling it as such. The actual summary is perfect as a first paragraph, rather than #TL;DR and then the summary. A picky point, to be sure. Jan 15 '14 at 1:17
  • @Kate, that actually makes sense. Not calling it out with a header could work too. I'll give it a test run see how I like it.
    – jmac
    Jan 15 '14 at 1:28
4

ES IST NOCH KÄSEBROT DA!

Headlines are an essential part of an answer if you need to get the message out or divide content.

Therefore I'd say it's accepted practice to use them sparely and distinctively if they serve a purpose, like my beautiful headline above.

Which actually is shouting as all uppercase, so the comment by that guy was a bit wrong, not bold, but uppercase text is normally considered as shouting, or in case of my headline, just a cheering expression of joy.

This is perhaps an example what should be considered not so good:

╔═══════════════════════════════╗

║ ♥ thank you for reading ... ♥ ║

╚═══════════════════════════════╝

9
  • Indeed, very, very bad.
    – Arjan
    Dec 31 '13 at 17:50
  • 2
    @Arjan, well on my computer it looks different. This perhaps should be avoided altogether :)
    – hakre
    Dec 31 '13 at 17:51
  • ...even when editing, the lines do not have the same length...! Some fonts are behaving badly on your machine?
    – Arjan
    Dec 31 '13 at 17:52
  • i.stack.imgur.com/aKake.png
    – hakre
    Dec 31 '13 at 17:52
  • (Your edit fixed it for me. Too bad the headers have this extra spacing that cannot be avoided in this example, I guess.)
    – Arjan
    Dec 31 '13 at 17:54
  • Well, there is a lot in Unicode to exploit for some attention grabbing Q&A, the more common way is to use images I guess.
    – hakre
    Dec 31 '13 at 17:59
  • Nope, I didn't knew that one, nice :D I love this one
    – hakre
    Dec 31 '13 at 18:22
  • 2
    ICH WILL DIESEN TEPPICH NICHT KAUFEN! Dec 31 '13 at 20:40
2

Keep accessibility in mind when formatting web content

Use formatting for its intended purpose. Please don't use it gratuitously! Screen readers provide structure and verbal cues for users who can't see the larger text size, different font, etc.

Headers

Sighted user get visual cues to help them organize information on a webpage: font size, placement, bolding, color, etc. Users of screen readers rely on programmatic headers <h1> to <h6> (Markdown # to ######) to convey structure.

WCAG 2.1 has guidelines on Using h1-h6 to identify headings

  1. Check that heading markup is used when content is a heading and the heading markup indicates the appropriate heading level for the content.
  2. Check that heading markup is not used when content is not a heading.

Point 1. above means that text should not be marked bold, italicized, etc., to convey content structure. Point 2. above means that headings should not be used to convey emphasis, mood, or any other text formatting.

Text formatting

Bold text indicates importance. Italics indicate emphasis in another voice or mood. Sighted users get different visual indicators for text formatting like these. Users of screen readers rely on programmatic text formatting for verbal cues of their special status.

The WCAG 2.1 has guidelines on Using semantic markup to mark emphasized or special text.

4
  • 1
    You start with a h2 and skip to a h4. That's not very accessible. (Though it is unfortunately common.)
    – Laurel
    Oct 7 at 16:38
  • Nobody prevents SO to render the # markdown as a H2 HTML, since H1 has already been used for the question title. Oct 7 at 16:45
  • @Laurel That was an accessibility oops on my part. See edit.
    – Super Jade
    Oct 7 at 17:00
  • 1
    So while I understand accessibility concerns, I think that "markdown" for database content (answers) forces a different perspective. We can't expect users to know the structure of the surrounding page. Today, questions are formatted by Stack as H1's. So does that mean that every answer (that uses headings) should start with H2? No, because (a) it would be not be logical to assume that users are going to look at the HTML markup for the page before doing markdown formatting on their answer, and (b) the page structure could change in the future. Oct 7 at 19:16
2

Old question that got dusted off today when I linked to it in this MSO question.

I really like Shog9's answer, but I go one step further, personally, in my use of headings.

I believe that, for answers, the least obtrusive use of headings is the best. By that, I mean that I use the smallest (highest numbered) headings possible for the structure of my answer.

So if I only have one level of heading to separate multiple sections of an answer, I use H4 (since I didn't realize until today that H5 was an option, and it's really only the same thing as adding a "bold" tag anyway):


Section heading

Some paragraph content.

Some more paragraph content.

Etc.

Next section

So on

Side Note: And apologies for the semantically incorrect use of blockquotes to indent. I spent 15+ minutes trying to get this example to indent properly with hard spaces and non-breaking spaces, but Stack has a formatting issue (it seems) when using Headings with non-breaking spaces.


In the extremely rare case that I might need two levels, I would add the H3 as the top level. But I would try to flatten out the structure first.

I understand that this "breaks the normal rules" when it comes to, say, always starting with an H1, followed by an H2, etc. But those rules are meant for the HTML page itself. Answers are not an HTML page. They are database content that gets inserted into an HTML page.

That database content, and the users who create them, are not expected to have any knowledge of the page into which they will be inserted. In a typical Stack question/answer, the current page structure is that the question title itself is formatted H1. So that technically means (if you take the W3C recommendations literally and try to apply them to Markdown) that any answer headings should start with H2.

But:

  1. How is the typical Stack user supposed to know this? Are they supposed to examine the page markup before using headings in their answers? (Rhetorical question - No.)
  2. There is no future guarantee that an additional heading level might be added by Stack, or even removed.

So no, IMHO Markdown formatting should not, and cannot, follow the "HTML Rules" for the use of headings.

It would be great if (pie in the sky) Stack could adjust the Markdown headings (and their formatting) to the semantic structure of the page itself, but this honestly seems like overkill.

2
  • <H4>, <H5>, and <H6> support was added in July of 2021. Prior to that, <H3> were the highest numbered headers which were supported.
    – Makyen
    Oct 9 at 6:55
  • In our current formatting style at least, there's a huge difference between H1 and H2 but smaller differences between H2 and 3 and 4 and 5... and H6 is just squishy and weird (do not recommend). I understand your line of thought but I think starting at the smallest and working up as needed doesn't really minimize the intrusiveness of the headers as much as you imply that it does, simply because H2 isn't that much more intrusive than H4.
    – Catija StaffMod
    Oct 9 at 13:54

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .