CommonMark (Markdown standard specification)

Share interesting information or links related to portable apps here.
Post Reply
Message
Author
User avatar
Midas
Posts: 6705
Joined: Mon Dec 07, 2009 7:09 am
Location: Sol3

CommonMark (Markdown standard specification)

#1 Post by Midas »

CommonMark v0.28 released, dated 2018-08-01 (https://spec.commonmark.org/changelog.txt).
This document attempts to specify Markdown syntax unambiguously. It contains many examples with side-by-side Markdown and HTML. These are intended to double as conformance tests. An accompanying script spec_tests.py can be used to run the tests against any Markdown program. [...] This document is generated from a text file, spec.txt, written in Markdown with a small extension for the side-by-side tests.

CommonMark is intended as an authoritative Markdown specification, which I have mentioned a few times around TPFC's forums (see viewtopic.php?p=73253#p73253, viewtopic.php?p=74072#p74072, and viewtopic.php?p=82416#p82416).

User avatar
webfork
Posts: 10818
Joined: Wed Apr 11, 2007 8:06 pm
Location: US, Texas
Contact:

Re: CommonMark (Markdown standard specification)

#2 Post by webfork »

Midas wrote: Fri Aug 10, 2018 10:12 am CommonMark is intended as an authoritative Markdown specification
That is remarkably thorough. I have been frustrated by the way different rendering tools have different standards and you have to relearn the process every time you pick up a new tool. Compatibility between different markdown tools would do a lot for the format overall and start to build something that's a real alternative to standard WYSIWYG interfaces. One tool might have better printing, another have more typeface support, while I can see others just having a bunch of text editor macros like NoteTab.

Also the analysis of MarkDown vs. AsciiDoc answers a question I've had for some time now. The "Try it" buttons are also helpful.

I have only questions at this point such as is this fully implemented? How could this get implemented on a broad scale? How can the format get improved or added to in the future? If something in MacFarlane's structure didn't make sense, how would you modify it?

User avatar
Midas
Posts: 6705
Joined: Mon Dec 07, 2009 7:09 am
Location: Sol3

Re: CommonMark (Markdown standard specification)

#3 Post by Midas »

webfork wrote: I have only questions at this point such as is this fully implemented? How could this get implemented on a broad scale? How can the format get improved or added to in the future? If something in MacFarlane's structure didn't make sense, how would you modify it?
As much as I am aware (I haven't really tested it), the code repository at https://github.com/CommonMark/CommonMark contains full implementations in both C and JavaScript (but there are others).

And given that MacFarlane is also the main developer of Pandoc (viewtopic.php?t=23800), I'm pretty positive he reflects the evolution of the spec in his own work sooner or later.
The current version of the CommonMark spec is complete, and quite robust after a year of public feedback... but not quite final. With your help, we plan to announce a finalized 1.0 spec and test suite in 2018.

Judging from that, my best guess is modifications can be submitted to the public discussion system at https://talk.commonmark.org/.

User avatar
Midas
Posts: 6705
Joined: Mon Dec 07, 2009 7:09 am
Location: Sol3

Re: Zettlr (Markdown editor)

#4 Post by Midas »

I'm adding a mention to Zettlr (https://www.zettlr.com/) here not because it is yet another un-portable Electron based Markdown editor (albeit nice looking)...

Image

But because the developer has some cool insights about Markdown scattered throughout the site -- such as this one:
Word processors as Microsoft Word or LibreOffice are simply not made for easy and focused writing. That's why there is Markdown. It keeps apart your content and your final styling of a text. This way you are not distracted by all the neat formatting options word processors offer you and focus only on your content. Styling is applied in a second step.

Another Zettlr cool feature is out of the box Pandoc support -- but if you're looking for a portable app for the job, check out QOwnNotes (viewtopic.php?t=23143).

User avatar
Midas
Posts: 6705
Joined: Mon Dec 07, 2009 7:09 am
Location: Sol3

Re: CommonMark (Markdown standard specification)

#5 Post by Midas »

CommonMark v0.29 was released 2019-04-06 (changelog at https://spec.commonmark.org/).

Quick note to add a couple of well known online Markdown editors -- good for opening/editing files in a hurry:

Also an illustrated online overview of basic Markdown syntax, annotated with some dos and don'ts:


User avatar
Midas
Posts: 6705
Joined: Mon Dec 07, 2009 7:09 am
Location: Sol3

Re: CommonMark (Markdown standard specification)

#6 Post by Midas »

Should we be wary of Google bearing gifts? It's unlikely an inception of a triple E (as in "embrace, extend, extinguish") strategy, but it'll have its consequences, IMHO.
Google is adding Markdown support to Google Docs on the web, letting you format your document using text shortcuts rather than keyboard ones. In a blog post announcing the feature, Google says it’s doing this through its autocorrect feature, so it will automatically format the text for you after you type it in Markdown format.

User avatar
Midas
Posts: 6705
Joined: Mon Dec 07, 2009 7:09 am
Location: Sol3

Re: CommonMark (Markdown standard specification)

#7 Post by Midas »

FYI, for an in-depth analysis of Markdown vs similar Asciidoc and reStructuredText text-based markups see the following article:
In the first part of my docs-as-code series, I'll talk about the choice of markup languages, the available frameworks, and do a comparison among Markdown (md), Asciidoc (adoc), and reStructuredText (rST) based on some use cases. [...] My hope is to provide you with a detailed analysis of these choices of markup languages so that you can make an informed decision when selecting one for your next developer documentation project.

Incidentally, the Open Web Documentation project switched from HTML to Markdown last year and you can now find a motivation explainer on their site:
In 2021, the Open Web Docs team, with help from Mozilla, the W3C, and the wider web docs community, converted the authoring format for MDN Web Docs -- all 11,000 pages of it -- from HTML to Markdown.

Here's somewhat of a contrarian viewpoint regarding Markdown:
I truly loathe Markdown. Truly. But given the widespread use of Markdown, it might seem strange that I have such aversion to it. If you somehow really like it, or are so used to it by now, you might be tempted to think I'm the oddball.

And, BTW, the CommonMark spec is currently at v0.30, released 2021-06-19 (cf. https://spec.commonmark.org/).

User avatar
Midas
Posts: 6705
Joined: Mon Dec 07, 2009 7:09 am
Location: Sol3

Re: CommonMark (Markdown standard specification)

#8 Post by Midas »

An interactive tutorial for anyone wanting to get the hang of CommonMark is now available at:
Each lesson introduces a single Markdown concept with an example. When you see a red pulsing circle in the example, select to examine it for details. After studying the example, try a few practice exercises with your new knowledge. Skip to any lesson at any time via the navigation controls.

Post Reply