Markdown: ATX-style headers should focus on consistency for justification

[brianary]

Headings with = or - underlines can be annoying to maintain and don’t fit with the rest of the heading syntax. The user has to ask: Does --- mean H1 or H2?

— Markdown style guide: ATX-style headings

The stated rationale for dismissing Setext headers due to confusion between = and - appears to be a pre-emptive use of the tu quoque fallacy, since there doesn’t seem to be any actual or likely confusion (===== is clearly a heavier/double underline vs -----), while ###### This is an H6 has much greater visual emphasis than # This is an H1, which isn’t much more visually distinct than a list item: * This is a list item. An atx H1 # This in an H1 being greater than an atx H2 ## This is an H2 is also inconsistent with Markdown syntax defining *emphasis* as less than **strong emphasis**, in terms of increasing decoration. Confusion is a bigger problem for atx than Setext.

Visually, a single # character is easy to miss, though it is meant to indicate the header of greatest importance. The # character also denotes a comment in many languages, and if you include any of those in your document, e.g. distinguishing between a PowerShell comment and an H1 header becomes quite context-dependent. Headers like # Products can even read as “number of products” when scanning a text quickly, especially when missing the context of the Markdown syntax in unrendered/unhighlighted environments like database field values.

# PowerShell command line options

The PowerShell executable offers several command-line parameters than can be abbreviated to the minimum
# of characters that disambiguate them. <!-- Careful: This will usually be rendered as a header, but not always! -->

```powershell
# good options for Scheduled Tasks and simple one-liners
powershell.exe -NoLogo -NonInteractive -NoProfile -File C:\Scripts\Backup-Data.ps1

# shortened
powershell.exe -nol -noni -nop -f C:\Scripts\Backup-Data.ps1

# simple one-liner to list Windows file shares
powershell.exe -nol -noni -nop -Command "& {Get-WmiObject Win32_Share}"

Underlining headers provides a strong, natural visual decoration.

Readability is the primary design goal of Markdown over other formats, and the ease of writing and parsing atx headers doesn’t contribute to that goal.

I've made an honest attempt at a fair and thorough comparison of the four possible Markdown headings at [Setext vs atx Header Styles in Markdown](http://webcoder.info/markdown-headers.html).

[zerosheepmoo]

I agree with your overall opinion. so what is your conclusion?

Recommend a setext style than atx? Or recommend an alternative atx-style? Or mixture?

And I'm careful to say, but is the rationale "really" silly?

The user has to ask: Does --- mean H1 or H2?

The above statement could be unreasonable according to your argument. However, how's the case of h3 or the others except for h1, h2? Even though too many headings (including h3 And lower level)are not recommended, using h3, h4 should be considered. Even if using h1, h2 as setext and others as atx, consistency is still the problem.

The stated rationale should be revised and fixed, but I am not sure if it is necessary to replace all ATX-style to setext.

[brianary]

I'd personally prefer Setext because I think it's visually clearer, but changing the rationale for atx from an argument of clarity to one of consistency and simplicity would be reasonable. Setext does imply mixed usage in the cases H3 and lower are used, but ### seems much more visible to me than a single #.

I could be wrong, especially without any user studies or other data as evidence, but ----- vs ===== does seem clear to me.

On Sun, Mar 28, 2021, 23:49 Youngmu Yang @.***> wrote:

I agree with your overall opinion. so what is your conclusion?

Recommend a setext style than atx? Or recommend an alternative atx-style? Or mixture?

And I'm careful to say, but is the rationale "really" silly?

The user has to ask: Does --- mean H1 or H2?

The above statement could be unreasonable according to your argument. However, how's the case of h3 or the others except for h1, h2? Even though too many headings (including h3 And lower level)are not recommended, using h3, h4 should be considered. Even if using h1, h2 as setext and others as atx, consistency is still the problem.

The stated rationale should be revised and fixed, but I am not sure if it is necessary to replace all ATX-style to setext.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/google/styleguide/issues/631#issuecomment-809117850, or unsubscribe https://github.com/notifications/unsubscribe-auth/AB7SMJ7VDMEP7B2LRK54P3TTGAPG3ANCNFSM4Z6M5TGA .

[zerosheepmoo]

It makes sense. I agree with changing the rationale. It must be fixed. (to consistency, simplicity) I think there is also no evidence that ATX-style is visually clear.

However, I still don't know which using method is better (in objective point of view) Waiting for more discussion might be the best.

I'd personally prefer Setext because I think it's visually clearer, but changing the rationale for atx from an argument of clarity to one of consistency and simplicity would be reasonable. Setext does imply mixed usage in the cases H3 and lower are used, but ### seems much more visible to me than a single #. I could be wrong, especially without any user studies or other data as evidence, but ----- vs ===== does seem clear to me.

[vapier]

it's helpful to keep in mind that style guides are written with different audiences. we don't expect people to be experts fully versed in the respective language, and writing it every day in order to make meaningful contributions. so in that context, the statement "Does --- mean H1 or H2" is not unreasonable. if I saw - and = in use, I would jump to the conclusion that - is H1 while = is H2 because the first has 1 line (ergo H1) while the second has 2 lines (ergo H2).

both those styles also suffer from the alignment problem -- if the preceding line changes, do you also extend/shrink the number of header chars to match ? or do you aim to use 3 all the time ? if the header text was 3 already, do people think it's a constant 3, or that's just a coincidence and they need to extend/shrink it to match ? we don't call this out in the markdown guide specifically because there aren't that many places where it'd come up, but you can see this in action in the markdown table section where it uses --- consistently, and doesn't align the |. it's also a common theme in other Google style guides. See Java on horizontal alignment for example.

either way, agreed that we should lead with consistency here since Setext is limited to H1 & H2 which means ATX will show up as soon as people want H3+.

I don't really buy arguments about # or --- being visually better or worse, or being easy to miss. this perspective wholly depends on what you're used to and what your brain neural network has been trained on. both of them are easily remedied by an editor with syntax highlighting.

[brianary]

@vapier

I would jump to the conclusion that - is H1 while = is H2 because the first has 1 line (ergo H1) while the second has 2 lines (ergo H2).

That argument makes as much sense to me as 48-point font indicating H48 headers. I don't really get why you'd count elements. It seems a pretty specious assumption. Speculative ignorance is typically self-serving in arguments.

Did you check out Setext vs atx Header Styles in Markdown? Important point: You can easily start a line with # in code blocks, which you can't really train your brain to treat differently if you expect that to be a heading; it's ambiguous without context.

Yes, the line length probably would change, or else it could just be a fixed number, I'm not sure it matters a lot. Optimizing for writing ignores the primary design goal of Markdown, though (optimized for reading).

[vapier]

you seem to have completely skipped over the part "the guide doesn't assume people are subject matter experts". it's great you didn't make that incorrect assumption, but assuming everyone else would follow the same path is a failure. I didn't make that example up, it's what I thought initially because I never use this style.

simpler consistent rules make it easier to jump in & contribute & get it right the first time. ATX accomplishes that goal.

realistically, you aren't going to move the needle on Google's style preferences in this space as ATX has been well established, and we strongly prefer consistency over random personal preferences. I don't say this to be dismissive of your opinion, just stating facts with how GH suggestions often happen. case in point: it's been 3 years before anyone responded here.

[brianary]

I assumed it was a personal experience, but that's an anecdote, not data.

Again, the stated, long-established priority is reading.

Setext is much more visible just by virtue of being physically larger. That's indisputable.

If you don't think it'll change, why bother to engage? Continuing to do something only because of inertia is a reactionary perspective, which works against progress.

[vapier]

you're attempting to substitute your personal preferences as established facts when they clearly aren't, while also simultaneously dismissing viewpoints you disagree with because they aren't "facts". each style has pros/cons, and you simply weigh them differently.

I already reframed the issue in how the docs can be improved. it isn't about changing the guidance.

[brianary]

I'm sorry, it seems you're projecting. See: You aren't even addressing my points, just ignoring them.

[brianary]

In any case, this isn't particularly constructive here. We can continue this elsewhere if you need, @vapier

[vapier]

if you want to claim something as fact, you need to cite peer-reviewed studies/sources. the only thing you've presented are statements you've personally authored. I'm not ignoring them, i'm taking them for what they are: your opinion.

I agree there's no point in discussing Setext usage as i've said multiple times now, and why I changed the scope of the issue to something actionable. if you want to send a PR to add consistency details, feel free, or you can wait for someone else to improve the guide along those lines.

[brianary]

@vapier Your contact info appears to be out-of-date.

There is a difference between opinion and examples. Do you require cited sources to establish that larger things are more visible, or that one H1 header style is ambiguous in content while the other is not? Which specific assertions do you feel require external validation? Please be more precise in your criticism.

Changing my request without my assent, in fact contrary to my request, is misleadingly putting words in my mouth. It's terrifically arrogant, and completely unacceptable.