to be recognized as:
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)
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.
Address: 32 tenne st, alighe, Cvornia
### 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
* Not ants
## References ##
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.
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”.
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 was editing some markup yesterday (wikitext, but the principle is the same) and came across a document formatted like this:
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.
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).
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.
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):
The World Wide Fund for Nature (WWF) is...
<p>The World Wide Fund for Nature (WWF) is....</p>
If the objection is that it takes 3 lines. Then the other alternative is to do this: