This is a minor annoyance, but I would like
==============
Header Title
==============
--------------
Header Title
--------------
to be recognized as:
not:
I use this in certain context, where it stylistically makes sense. For example you would use this in a resume. It makes a long document easy to scan with the eye, since you can recognize the double header as being a major section break.
For consistency it would be best to apply this rule to both first and second level setext headers. That could introduce problems, for example a clash with horizontal rules and also the Jekyll-style meta data syntax if it is used in an extension.
Wont be an issue with horizontal rules, since you are checking this sequence:
\n\n + setext headers + \n + header text + \n + setext headers
horizontal rules would have newline on top and bottom.
\n\n + setext headers + \n\n
Jekyll style metadata header would be an issue however. But it would have to be a single line metadata, and I’m not sure if that is common enough to worry about. If it is, how would you tackle this? (but if we are going to use % for single line metadata, then why not %%% fencing?)
See Example 20 in the spec, a heading which is not surrounded by blank lines. So some rules would need to be changed, potentially breaking existing Markdown documents (but I am speculating here).
Regarding Jekyll-style meta data, it depends what you think is the more important feature. We already have three ways of writing second level headings, so perhaps this feature, while nice, is overkill.
I have a feeling I’ll be using this more. Since I do get pretty annoyed at trying to distinguish certain section headers.
Also instead of Jekyll syntax. We could perhaps use my current thought in this post Metadata in documents . Where I propose that we place metadata just under headers or rulers (assuming that these metadata is placed in attribute of an entire section.)
Alternatively, we could just use generic directive !metadata: (edit: maybe this presents the information in it’s own dedicated meta tag, while the other example above places it in the attributes).
Also no issue with example 20 . Not saying that we should remove the single setext version. Just saying to also detect double setext as well. (If you see setext text then text then setext, then it is a header. If text then setext, then it is also a header)
previous section with a line break below
---
Second level heading
---
There are potentially Markdown documents out there which would intend for the first --- to translate into a horizontal rule (closing off the previous section).
Hmmm… okay, say in a resume. Does flowerbox header indicate perhaps both a new “theme” <hr> and a header <h1>? For single setext, it’s just a normal header.
Have a look at this mock resume, and tell me what you think about double setext’s meaning.
===================
JOHN BUREN
===================
Address: 32 tenne st, alighe, Cvornia
Phone: 32334232
Email: johnburen@example.com
---------------
Education
---------------
### The University of Cvonia (Tertiary)
| Bachelor of Philosophy (2000 - current)
| Major in Cybernetics
### Leage High School (LHS) (Secondary)
| CET: (SCORE 97.5)
| Slegddon top, North Walf
---------------------------------
Work / Volunteer Experience
---------------------------------
### Clean up Cvonia Day (2012)
| Where we cleaned up all the rubbish etc...
--------------------------------------
Interests, Activities, Abilities
--------------------------------------
* Cats
* Dogs
* Birds
* Not ants
----------------
## References ##
----------------
etc...
Alternatively, we just chalk it up to progress yo and just implement it. Not very semantic to be placing horizontal lines too close to another header anyway.
The document declaration will help with choosing the right behaviour.
It looks nice, and I agree placing horizontal lines close together does not look visually appealing.
Breaking backward compatibility is problematic though and I’m opposed to document declarations for Markdown (or other programmer-like switches for enabling/disabling features). Refer to my post in the declaration tag topic.
Still falls back as text, so it’s not a horrible collapse on the original markdown parser.
E.g. this is how it actually fails (according to http://spec.commonmark.org/dingus.html)
===================
JOHN BUREN
===================
AND
----------------------
JOHN BUREN
----------------------
Is rendered like:
START OF EXAMPLE___________________________
=================== JOHN BUREN ===================
AND
#JOHN BUREN
END OF EXAMPLE_________________________________
And this is reasonable, especially for the second example. For commonmark. Well we are still not V1 yet, so all the more reason to get this in.
In current markdown parsers out there, my approach is:
--------------
# Header 1 #
---------------
## Header 2 ##
But i prefer the flowerbox header (since I rather not render horizontal lines for every header)
edit: more distinctive naming for header type.
Setext headers do not go on the top and bottom, they are exclusively on the bottom of the heading. Requesting this change diverges in a significant way from the original markdown spec. I’m more of a purist in that I’d like to keep the core spec as close to the original as possible, with the edge cases explicitly called out.
I think this would make a reasonable extension request so long as you give it a different name. Calling it “setext headers” is misleading. I would call it “flowerboxing headers”.
Box header perhaps? Then again flowerbox header is more distinctive, so we can go with that.
About keeping to markdown. We can either keep to original spec like fundamentalist, or we can improve upon it like progressives (reminds me of religion). Both has it’s importance.
In this case however, there is an advantage in readability (easier to see important header divisions) that is bigger than the divergence from baseline spec.
I’m not against making changes, I’m of the opinion that significant changes should be called out as optional extensions so that existing valid implementations continue to be valid implementations.
Of course there will likely be minor bugs in the spec, or edge cases that get called out that a valid implementor would need to address to stay valid, but these should be minimal.
Fair enough, that’s a very valid point. Hmmm… so again my core point is that this is really only a minor extension to the original setext header, but the cost is offsetted by the advantage of being able to clearly make distinction between major header sections in a document.
I’d not do that at all.
To achive this kind of format might be better use the block attribute extension.
e.g.:
# NAME {.box}
I was editing some markup yesterday (wikitext, but the principle is the same) and came across a document formatted like this:
Heading Paragraph Text Heading Paragraph Text
There are only single line breaks between headings and paragraphs. This demonstrates that there are existing documents are formatted is this way. If backward compatibility is a concern, it is dangerous to change the behaviour, even as an extension (which we should aim to degrade gracefully).
From the front page of commonmark.org, the description of CommonMark is (emphasis added):
A strongly specified, highly compatible implementation of Markdown.
And this:
We propose a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate Markdown implementations against this specification. We believe this is necessary, even essential, for the future of Markdown.
For better or worse, this is a conservative goal, not a progressive one. To formalise Markdown, not progress the language in a way that breaks backward compatibility.
The flowerbox header is an alias of setext header. It has no styling.
I see. 
well hopefully there is a home for this concept then. Like an official commonmark extended specification, that can afford to break compatibility in the name of progressing towards the spirit of markdown (visual readability).
It isn’t that readable having additional visual elements (I’m one that would keep just the # notation…)
When doing text resumes, or presentable text files. I do find # to be rather ugly. And when you have a large document that consist of purely of # &/or setext headers, it can be rather hard to distinguish between sections unless you use horizontal rules. But horizontal rules is more of a hack. And I don’t like hacks.
the heading do not say much about sections and we do not have explicit section-markers =/
hmmmm…
…
Well, what’s not to say that this flowerbox header could be a way to provide both “section” and “header” at the same time? (thus if you don’t want sections, you use normal setext. If you want sections, you use flowerbox headers):
====
WWF
====
The World Wide Fund for Nature (WWF) is...
leads to
<section>
<h1>WWF</h1>
<p>The World Wide Fund for Nature (WWF) is....</p>
</section>
If the objection is that it takes 3 lines. Then the other alternative is to do this:
============
# header 1 #
--------------
## header 2 ##
-----------------
### header 3 ###
etc...