cmark

My personal build of CMark ✏️
Commit: 8c80f2d5b5f5230be6c842be741d8c1468ee01db
Parent: 91a9a99d328a1057b28964c35c8da71825d8a306
Author: John MacFarlane <jgm@berkeley.edu>
Date: Sat, 30 Aug 2014 11:37:28 -0700
Added narrative.md, source for index.html in site.
Diffstat

1 file changed, 121 insertions, 0 deletions
Status	File Name	N° Changes	Insertions	Deletions
Added	narrative.md	121	121	0
diff --git a/narrative.md b/narrative.md
@@ -0,0 +1,121 @@
+---
+title: Standard markdown
+...
+
+Standard markdown is a [specification of markdown
+syntax](http://jgm.github.io/stmd/spec.html), together with
+BSD3-licensed implementations (`stmd`) in C and javascript. The source
+for the spec and the two implementations can be found in [this
+repository](http://github.com/jgm/stmd).
+
+The C implementation provides both a library and a standalone program
+`stmd` that converts markdown to HTML. It is written in standard C99 and
+has no library dependencies.
+
+The javascript implementation is a single javascript file, with no
+dependencies. [Try it now!](http://jgm.github.io/stmd/js/)
+
+[The spec](http://jgm.github.io/stmd/spec.html) contains over 400
+embedded examples which serve as conformance tests. (The source contains
+a perl script that will run the tests against any markdown program.)
+
+The spec is written from the point of view of the human writer, not the
+computer reader. It is not an algorithm—an English translation of a
+computer program—but a declarative description of what counts as a block
+quote, a code block, and each of the other structural elements that can
+make up a markdown document. For the most part, the spec limits itself
+to the basic elements described in John Gruber’s [canonical syntax
+description](http://daringfireball.net/projects/markdown/syntax),
+eschewing extensions like footnotes and definition lists. It is
+important to get the core right before considering such things.
+
+Because Gruber’s syntax description leaves many aspects of the syntax
+undetermined, writing a precise spec requires making a large number of
+decisions, many of them somewhat arbitrary. In making them, I have
+appealed to existing conventions and considerations of simplicity,
+readability, expressive power, and consistency. I have tried to ensure
+that “normal” documents in the many incompatible existing
+implementations of markdown will render, as far as possible, as their
+authors intended. And I have tried to make the rules for different
+elements work together harmoniously. In places where different decisions
+could have been made (for example, the rules governing list
+indentation), I have explained the rationale for my choices. In a few
+cases, I have departed slightly from the canonical syntax description,
+in ways that I think further the goals of markdown as stated in that
+description.
+
+There are only a few places where this spec says things that contradict
+the canonical syntax description:
+
+-   It allows all puncutation symbols to be backslash-escaped, not just
+    the symbols with special meanings in markdown. I found that it was
+    just too hard to remember which symbols could be escaped.
+
+-   It introduces an alternative syntax for hard line breaks, a
+    backslash at the end of the line, supplementing the
+    two-spaces-at-the-end-of-line rule. This is motivated by persistent
+    complaints about the “invisible” nature of the two-space rule.
+
+-   Link syntax has been made a bit more predictable (in a
+    backwards-compatible way). For example, `Markdown.pl` allows single
+    quotes around a title in inline links, but not in reference links.
+    This kind of difference is really hard for users to remember, so the
+    spec [allows single quotes in both
+    contexts](http://jgm.github.io/stmd/spec.html#links).
+
+-   The rule for HTML blocks differs, though in most real cases it
+    shouldn't make a difference. (See
+    [here](http://jgm.github.io/stmd/spec.html#html-blocks) for
+    details.) The spec's proposal makes it easy to include markdown
+    inside HTML block-level tags, if you want to, but also allows you to
+    exclude this. It is also makes parsing much easier, avoiding
+    expensive backtracking.
+
+-   It does not collapse adjacent bird-track blocks into a single
+    blockquote:
+
+        > this is two
+
+        > blockquotes
+
+        > this is a single
+        >
+        > blockquote with two paragraphs
+
+-   Rules for content in lists differ in a few respects, though (as with
+    HTML blocks), most lists in existing documents should render as
+    intended. There is some discussion of the choice points and
+    differences [here](http://jgm.github.io/stmd/spec.html#motivation).
+    I think that the spec's proposal does better than any existing
+    implementation in rendering lists the way a human writer or reader
+    would intuitively understand them. (I could give numerous examples
+    of perfectly natural looking lists that nearly every existing
+    implementation flubs up.)
+
+-   The spec stipulates that two blank lines break out of all list
+    contexts. This is an attempt to deal with issues that often come up
+    when someone wants to have two adjacent lists, or a list followed by
+    an indented code block.
+
+-   Changing bullet characters, or changing from bullets to numbers or
+    vice versa, starts a new list. I think that is almost always going
+    to be the writer's intent.
+
+-   The start number of an ordered list is significant.
+
+In all of this, I have been guided by eight years experience writing
+markdown implementations in several languages, including the first
+markdown parser not based on regular expression substitutions
+([pandoc](http://github.com/jgm/pandoc)) and the first markdown parsers
+based on PEG grammars
+([peg-markdown](http://github.com/jgm/peg-markdown),
+[lunamark](http://github.com/jgm/lunamark)). Maintaining these projects
+and responding to years of user feedback have given me a good sense of
+the complexities involved in parsing markdown, and of the various design
+decisions that can be made. I have also explored differences between
+markdown implementations extensively using [babelmark
+2](http://johnmacfarlane.net/babelmark2/). In the early phases of
+working out the spec, I benefited greatly from collaboration with David
+Greenspan, and from extensive discussions with a group of industrial
+users of markdown, including Jeff Atwood, Vincent Marti, and Neil
+Williams.