The stated rationale for atx-style Markdown headers is specious and silly

[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.

[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.