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 decisions, less experienced ones will have to (or worse, write without a consistent style…).
If there’s interest in a style guide we could look at adding a section to the new CommonMark website that I’m in the process of building.
It’s worth questioning whether a particular style is something that this project should be recommending. One of the features of Markdown is that it appeals to multiple aesthetic styles - longer, more readable syntax (reference links, setext headers, explict quote markers on every line) and shorter, easier to type syntax (inline links, atex headers, lazy quote markers). The CommonMark project having an opinion on which style is best would likely be controversial.
What kind of info will your website contain? Is it open sourced / will it be? Can you show what you’ve got so far?
The CommonMark project having an opinion on which style is best would likely be controversial.
I agree, it’s a hard choice. Begin joke: Any choice made by CommonMark is likely to be controversial given the current incompatibilities amongst implementations.
My style guide is not suitable for non technical people since it requires HTML and diff understanding for the rationale, and it is too detailed. But if you think something could be extracted, that would be great.
I would recommend to just follow a style guide on the examples that you give users, or when you mention multiple possible syntaxes quickly recommending one of them, as that will determine how beginners write to a large extent.
For the “Quick Reference” guide, I’m considering only explaining one style for each feature (e.g. headers) to keep the guide concise. There could then be a link to the longer guide for each element which would explain how to use multiple styles. The problem is choosing which styles to favour in the Quick Reference. There are advantages with using shorter syntax (easier to write) and longer syntax (sometimes easier to read).
I think having an “official” style guide at the commonmark.org domain would be very valuable. People can always invent their own style guide if they wish. Most programming languages have official style guides, so I don’t see why CommonMark can’t have it too? I think this particular Markdown style guide is a very good starting point.
As mentioned earlier, a lot of the style differences in Markdown come down to a choice between being easy-to-read and easy-to-write. Neither approach is right for every situation.
But perhaps there is value in a “high readability” style guide. Such a style guide would encourage setext-style headers, asterisk lists, block quote markers on every line, indented code blocks, etc over their easier-to-type counterparts. This blog post that @codinghorror linked to earlier would be a good starting point for a high readability style guide.
I had a quick look at the guide you linked to @asbjornu. The choices seem somewhat arbitrary. For example, hyphens are chosen for list markers (because they are easier to type than the more bullet-like asterisks?) but horizontal rules must be 80 characters wide for readability (but harder to type). If we used a guiding principle such as high readability, where syntax is chosen because it looks closer to what it represents, this would result in documents that feel more cohesive.
I’d rather optimize for readability as well, agree some points are inconsistent.
Asterisks for lists is something I’d like to change.
Setex is more readable, but does not scale (only level 2 defined). Syntax highlight it becomes really fine.
But yes, depending on editor features for readability is not good…
In any case, I think an option system is inevitable, people are never going to agree. Maybe having well defined options / standardization points is as much as we can do.
What I’ve tried most is to give the pros and cons of each choice.
We could also define two profiles:
one for readability that picks all readability optimizations
one for writability, which might be better when everyone is going to read rendered output all the time (e.g. stack overflow / github issues)
It’s quite common to read a Markdown file in a code editor (for example, a project’s README.md), in which case wrapping is likely turned off. What, if any, readability disadvantages are there for requiring an 80 character line limit?
Setext-style for level 1 and 2 headings, ATX for heading levels 3-6? This would ensure that levels 1 and 2 stand out more than levels 3-6; the most important section headings would show up when scrolling through a long document.
I think it’s more a matter of taste. I think - looks better than *. Cleaner and leaner. I think both choices are optimized for reading, but agree that if your taste is different, it might seem arbitrary.
When in doubt, opt for consistency, imho. So ATX for all heading levels. The reason I linked to this style guide was that I agree with all the choices made there.
Hi Ciro, I was confused by who or what the style guide was for. It would help if the intended audience and purpose were explained in the intro to the document. So this is for people who are writing a Markdown source document? Why would we need a style guide for that, given that Markdown is meant to be processed and rendered? I almost never read raw Markdown, but maybe others deal with it more.
The hard line breaks at 80 characters lead to broader problems. I didn’t realize until recently that the reason so many e-mails are broken, especially on mailing lists, is that Unix/Linux users are writing them in plain text and hard wrapping each line at some cutoff (e.g. the MUSL C library listserv). You’ll see lots
of e-mails that look
like this
because of this bizarre custom from the early 1990s.
Hard wrapping plain text is like using plastic grocery bags – it has downstream consequences as the content finds its way into other mediums, like e-mail. At some point we have to note that it’s 2016, and computers can automatically wrap lines, render crisp proportional fonts, talk to us, etc.
Why would we need a style guide for that, given that Markdown is meant to be processed and rendered?
As I tried to explain at Markdown Style Guide - Ciro Santilli for source code documentation, some people may consider readability also important, as it will be often read directly after a git clone.
I dislike the 80 line limit as well, and don’t use it for myself. It is there because that is what GitLab used.
I hadn’t considered the email rationale, I will add it as well.
One case where 80 line limit might be needed is if you are writing code comments in markdown, e.g. do document functions. In this case it will very often be read on source directly (although it will also be targeted by some export tool), and in many (inferior lol) languages newline has meaning, so soft wrapping is not an option.
Yes, I think the 80 character line limit is important for formatting reasons, when the Markdown is viewed as source. Although Markdown is closer to plain text than actual programming languages, it is still a form of source code. In the original Markdown syntax guide Gruber writes “Markdown’s email-style blockquoting and multi-paragraph list items work best — and look better — when you format them with hard breaks.” and I agree with him on this point. Compare these two ways of writing a list.
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
The former list clearly looks neater than the latter, but takes slightly longer to type. This is a good example of readability vs writability.
Just a quick post to say that as of November last year, Prettier now supports Markdown. Their implementation, which is CommonMark-compliant, will clean up the style of a Markdown document in a number of ways. I particularly like the automatic word wrap and ordering of list item numbers.
) don’t make those hard decisions, less experienced ones will have to (or worse, write without a consistent style…).
given the current incompatibilities amongst implementations.
