when using a first-level markdown heading (#) in a topic will that result in h1 or h2 in the HTML output?
It will output a <h1> 
1 Like
so does that mean that Discourse assumes that it’s nice to have multiple <h1> tags in a page? Seems like if the topic title is h1, then first-level headings inside that topic should be h2 by default, no?
1 Like
Discourse doesn’t assume anything, it will output what you ask it to output.
It’s better practice to use ## to use ### as top-level headings inside a post for sure
edit: see Use of H1 vs. H2 headings in composer - #16 by Canapin
2 Likes
That is definitely some “user education” I think we could spare ourselves by not making # be a level 1 heading… 
Do you know if there is any way to change that? Or at least hide level 1 headings in the toolbar? (I’m guessing people writing directly in Markdown are a realistic education target…)
1 Like
Yes, it’s pretty straightforward. The list element has a data-name="heading-1" attribute that you can target with CSS
1 Like
Heh - I was just looking into it too. In a quick test, this hides the H1 option in both the markdown and rich text composer:
button[data-name="heading-1"] {
display: none;
}
(I may just keep this! I don’t see much reason to offer H1 in the composer.)
2 Likes
I can see your point, but this isn’t something that Discourse necessarily decided one way or another. Discourse follows a markdown convention called CommonMark, and it specifies that # should be converted into an H1. I think this convention for how markdown headings are converted to HTML tags is pretty standard across major markdown specifications.
2 Likes
Well, two <h1> headings isn’t that big question actually. It is really old SEO meme, that hasn’t been an issue long time now. Google etc. will use the first one or what ever they think is the most suitable.
We can discuss if two main headers is the most smart move contwnt wise, but when a platfprm will use different style for topic name and headers in posts it doesn’t really matter.
Still it is more suitable to use ##/<h2> in posts. But because it doesn’t play any actual role, my opinion is it is better that users use some headers that avoid those because they are afraid of using ”wrong” headers 
2 Likes
Headings may only be a small signal for SEO today – but I still dislike multiple H1s because I’m a nerd. 
I’m also thinking about how Steph is creating printable documentation for Page Publishing, where H1s in the post are rendering even larger than the page top H1:
Making those H2 would keep them slightly smaller than the top H1:
1 Like
Yeah that’s the problem. For me it’s natural to use the first-level header first, but if the theme isn’t styled with the same assumption, it’s messy. There’s a kind of disconnect here.
(Side-note: is it showing the doc to you en English without intervention of your part?!?)
That’s natural, yes, and it makes sense when you’re building a web page from scratch. But a CMS or publishing system almost always gets the page’s H1 from a title field, so you’d typically reach for H2 for the content sections.
(And I used the web browser’s translation tool to get English.)
1 Like
I agree. But we shouldn’t expect community members to have to know that, imho
Yep – and I see no downside to just hiding the H1 option.
Though I don’t see much use of headings by most users making typical posts. Folks making longer documentation topics probably have (or quickly will have) a little more experience with ## and that “TT” icon.
2 Likes
Also: I just noticed this interesting old discussion where it’s suggested that headings should only be used in topics, and disallowed in replies: Disable headers in replies like h1 and h2
If that’s of interest to anyone, this little snippet totally hides the “TT” headings icon in the composer only when replying:
.composer-action-reply button.heading {
display: none;
}
1 Like
Headings aren’t only about SEO but also accessibility stuff.
Screen readers can hop from one heading to another, and we can specify the header depth with keyboard shortcuts.
Topics have their <h1> titles, but every reply is prepended by its own hidden <h2>, visible with screen readers:
<h2 aria-hidden="false" class="sr-only" id="post-heading-9">
post by Jagster 4 hours ago
</h2>
So, in any case, when you post a <h1> or a <h2> heading in your content, it will always be a descendant of a pre-existing <h2> 
I’d say that, using headings above <h3> in a post might make screen-reading navigation a bit weird.
While it’s not consistent among existing topics, the post template from Customization > Plugin uses <h3> as top headings:
| | | |
| - | - | - |
| :information_source: | **Summary** | In a few words, what does this plugin do? |
| :hammer_and_wrench: | **Repository Link** | <> |
| :open_book: | **Install Guide** | [How to install plugins in Discourse](https://meta.discourse.org/t/install-plugins-in-discourse/19157) |
<br>
### Features
Describe the major features of the plugin
### Configuration
Include detailed steps on how to configure the plugin (include screenshots where necessary)
### Settings
Include a table of settings and setting descriptions
| Name | Description
|-|-|
|
Interestingly, this is not the case for Customization > Theme and Customization > Theme component templates, but their template contain no headings. Perhaps this should be changed.
4 Likes
Agreed. I’m a bit nerdy too and like my heading hierarchy to be clean.
So actually, in a post we should only use h3 h4 h5 if we want to do things right — might be interesting to have some kind of theme component that « fixes » that, would mean removing higher heading levels from the buttons and « translating » the styling for h3 and below in topics so it looks right when we use them…?
There is also h6 in case you need one more level in posts, but it’s tiny
H5 is also smaller than the normal text in the post, so I am not sure I’d use that
this is h5
2 Likes
Ah, I didn’t realize that! Probably explains Pfaffman’s comment that “the first level of header in a post should be an h3” [1]
The CSS hack then becomes:
button[data-name="heading-1"], button[data-name="heading-2"] {
display: none;
}
Thanks for addressing accessiblity – I’m working on keeping that in mind.
3 Likes
