Markdown "best practices"

[clbarnes]

Firstly, thanks so much for this project and community in general - the markdown ecosystem was (and in many spheres, still is) in dire need of this exact project.

Commonmark’s aim was to tie together disparate implementations to construct a single, flexible, relatively portable spec, covering most use cases. It has succeeded in this! However, in its goal to be most things to most people, there necessarily exists some vestigial duplication which makes the spec and new parsers more complicated and less approachable than they need to be. I do not suggest changing the spec to avoid this: rather, I wonder whether a parallel document (or annotations to the existing spec) which addresses degenerate features and recommends a “preferred” way of doing things (possibly with some reasoning) would be valuable to the community.

To borrow from the Zen of Python: There should be one-- and preferably only one --obvious way to do it.

For example (and this is not the place for splitting hairs over exactly what the preferences would be), such a document may suggest preferring ATX headings over setext, because they are more flexible and less ambiguous. It may go on to recommend that trailing # symbols are not used, and that the leading # symbols are not indented. Unordered lists should prefer hyphens; ordered lists should prefer <number><period> ; code blocks should prefer triple backticks; thematic breaks should use exactly three asterisks with no spaces; emphasis should use underscores, etc. Justifications can concern legibility, portability, discriminability from other language constructs, similarity to the HTML rendering, or any of the above. In some cases (like unordered lists), the decision can explicitly be arbitrary if there is no good justification one way or the other - but having a guideline is valuable in its own right (see spaces vs. tabs in python’s PEP8).

I suspect that the pressure Commonmark can exert on the markdown community at large may not be enough for these practices to instantly become convention, but it may be the only organisation which can authoritatively host such a document (whether or not attention is paid to it). It would present a smaller surface area for early-stage or lightweight parsers to target, further enhance portability for existing parsers where only a subset of Commonmark is supported, and be easier to learn and teach. And with best practices officially written down somewhere authoritative, everyone’s markdown could start looking more like everyone else’s markdown.

Such a document could be referred to as Minimal Markdown, or minimark.

I suspect that GitHub must have already made a lot of these sorts of decisions, because in converting their old sundown-compliant comments to commonmark-gfm, they must have had a way of resolving ambiguities from the AST.

[chrisalley]

Related discussion:

Style Guide for CommonMark

I am developing a Markdown Style Guide at: http://www.cirosantilli.com/markdown-style-guide Comments and alternatives are very much appreciated. I started it before CommonMark was released, but I believe that it works well for CommonMark as well. I also recommend adding a style guide to the CommonMark project: I totally understand if you think this might be out of scope, but the bottom line is: if experienced users (read: CommonMark core devs, not me ) don’t make those hard dec…

[vas]

@clbarnes

However, in its goal to be most things to most people, there necessarily exists some vestigial duplication which makes the spec and new parsers more complicated and less approachable than they need to be.

The things you mention are not “vestigial duplication”. They were designed into Markdown from the very beginning.

@clbarnes

To borrow from the Zen of Python: There should be one-- and preferably only one --obvious way to do it.

For example (and this is not the place for splitting hairs over exactly what the preferences would be), such a document may suggest preferring ATX headings over setext, because they are more flexible and less ambiguous.

I don’t agree. Comparing Markdown to Python is apples to oranges.

Markdown has what I call the Prime Directive, in the beginning of Gruber’s spec and also quoted in the CommonMark intro:

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

From a purely plain text readability point of view, Setext is better than ATX. Short, standalone underlined phrases are unambiguously headings. Double and single underlines clearly signify heading and subheading (when they co-exist).

If you ask someone to write a document in plain text, not based on any standard but simply in terms of readability and semantics, for headings they will use short centered lines, all caps, underlines, or some combination of these. No one will naturally use ATX style.

The only limitation of Setext is that it is limited to two levels. Adding more levels with other underline characters destroys the aforementioned clarity of heading vs subheading. The only reason ATX exists is to support more than two levels.

I suspect Gruber’s reasoning went like this:

1. Setext is more readable.
2. But ATX supports more levels.
3. But more than 2 levels is needed probably less than 10% of the time. For that 10% I don’t want to penalize the 90% and undermine the Prime Directive.
4. But it doesn’t hurt to support that 10% by also supporting ATX.

Likewise providing multiple options for list indicators is prioritizing the writer/reader over the parser. It’s not such a bid deal for parsers to support such options. It allows the writer to choose what looks best.

Best practices? Follow the Prime Directive! Do what is more readable!

[codinghorror]

@vas

Markdown has what I call the Prime Directive, in the beginning of Gruber’s spec and also quoted in the CommonMark intro:

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

Yes, that’s definitely been the goal since the beginning, and it’s good for everyone to keep that in mind.

CommonMark only adds “…and let’s try our best to make it consistent across implementations” to that, if anything.

[clbarnes]

I accept the pushback against the heading thing, but would like to draw attention to

@clbarnes

and this is not the place for splitting hairs over exactly what the preferences would be

The document I proposed was intended to be a set of suggestions to improve readability (by making markdown look as similar as possible). If you’re teaching someone markdown from scratch, is it really easier to tell them “it is absolutely necessary for you to know all 3 ways to make parseable ULs, 2 ways to make OLs etc.”, or to make an arbitrary choice to recommend they start with? And if we’re making arbitrary choices, wouldn’t it be nice for the community to settle on the same choice to make it as recogniseable as possible? In these cases, readability and publishability aren’t affected at all, but writability is improved.

[vas]

@clbarnes

If you’re teaching someone markdown from scratch, is it really easier to tell them “it is absolutely necessary for you to know all 3 ways to make parseable ULs, 2 ways to make OLs etc.”, or to make an arbitrary choice to recommend they start with?

It’s as simple as: You can make a bullet with -, + or *. Use whatever you fancy.

If you overthink it, you teach the person you are teaching to overthink it, needlessly making Markdown harder than it is.

Way back when the iPhone came out I thought of making an app to help people calculate tips. It was going to be real fancy, letting you tip the percentage you want, or give you a even dollar total if you prefer, and even help you split the tip with other people in even dollars. Then I realized that the very act of doing this would undermine something far more important: being generous. Just follow a simple rule, and round up (In New York, take the tax, double it). The wrong way to teach people the importance of generosity is to give them an app that is all about bean counting.