19 ms·
A Formal Spec for GitHub Flavored Markdown
- libeclipse 10y agoI'm really happy to see this. It's actually quite frustrating that although markdown is so nice, it barely has a consistent standard. It's almost impossible to use it cross-service. Hopefully now that Github has standardised their own flavour of it (and quite a nice flavour too), more people will start to use it. Of course there is the obligatory XKCD: https://xkcd.com/927/ https://xkcd.com/927/
- zzleeper 10y agoI would argue that it is consistent now. At the lowest level, you have commonmark. Then, you have extensions at the top, such as GFM. If Pandoc/Github/Reddit/SO/kramdown switch, that accounts for almost all front- and back-end cases that I care about. And given that the first four were actively involved with commonmark, I would take as given that they will support commonmark or a superset of it.
- kccqzy 10y agoPandoc already supports different flavors of markdown (commonmark included) and you can add/remove extensions to base flavors.
- legulere 10y agoIt's a specification based on the commonmark specification. Both are not a formal specs. They are more of an informal specification with some edge-cases listed (in contrast to the original markdown specification which has known unspecified edgecases).
- UK-AL 10y agoI really wish their was concise formal spec for markdown, rather than a multi-page essay. It makes it incredibly difficult for anyone trying to create something to parse it. There is no mechanical way for go from spec -> parser. I think its quite difficult to do though.
- adrianN 10y agoIs it really useful to write a formal spec for Github Markdown? The software they use to parse and render it is open source. If you want to know how exactly something works, you can read the source.
- scrollaway 10y agoIs it really useful to write a formal spec for HTML? The software we use to parse and render it is open source. If you want to know how exactly something works, you can read the source. ;)
- UK-AL 10y agoReading the sources and trying to understand it takes a lot longer than looking at bnf and cranking out recursive descent parser based on it or a parser generator.
- dreamcompiler 10y agoIt's not possible to write a BNF for Markdown. At least not an unambiguous, useful BNF. http://roopc.net/posts/2014/markdown-cfg/ http://roopc.net/posts/2014/markdown-cfg/
- legulere 10y agoYes, if you also want to have more implementations, that can differ in e.g. license or programming language. For instance it is the reason why there's no reimplementation of TeX.
- adrianN 10y agoThere is pdflatex, luatex,... Nobody stops you from translating the Ruby or whatever into your favorite language.
- jws 10y agoHaving used and maintained a Swift translation of the StackOverflow .NET markdown processor, please, when there is a proposal to use source as a spec, burn it with fire. Scatter the ashes.
- Ericson2314 10y agoI hate calling things formal which aren't. Also, I hope this puts to rest any idea of Markdown being "simple".
- legulere 10y agohttps://github.github.com/gfm/#disallowed-raw-html-extension- https://github.github.com/gfm/#disallowed-raw-html-extension... Why this? This is not a working blacklist to prevent XSS (e.g. onload="...")
- Xylakant 10y agoIt's not meant as an xss prevention but as a safety to prevent rendering errors.
- tanoku 10y agoHi there! As the spec explains, this is a Markdown specific blacklist that prevent the tags that would otherwise "break" the content of the Markdown document. A document that contains these tags will not be parsed properly by an HTML5 compliant parser; the parser will "swallow" other chunks of Markdown content that come after the tags. Hence, we disable the tags altogether. This is an UX feature, not a security feature. XSS prevention, and a plethora of other security checks, are performed by our user content stack -- but this functionality is shared for all markup languages in GitHub (MD, RST, ASCIIDOC, ...), so it's not discussed in this spec.
- scrollaway 10y agoWow, TIL about the <plaintext> tag. Here I thought I knew most of the corner cases of HTML.
- dbbk 10y agoWhat's bonkers to me is that there is no closing tag, everything after it is no longer parsed as HTML.
- jeffmcjunkin 10y agoIt's also a great way to check if user input's being parsed server-side! :)
- ptx 10y agoIf it disallowed certain words (i.e. treated them specially instead of just reproducing the text as written) such as "</plaintext>" it wouldn't be plain text.
- simplehuman 10y agoThis is great! A couple of years back, there was a failed attempt at standardizing this - http://www.vfmd.org/ http://www.vfmd.org/ and http://www.vfmd.org/vfmd-spec/specification/ http://www.vfmd.org/vfmd-spec/specification/. GitHub given it's popularity will surely succeed more.
- zeveb 10y agoThere was also Common Mark (http://commonmark.org/ http://commonmark.org/), which failed IMHO mostly due to John Gruber taking offense at their first choice of name, Common Markdown. Will formalising this as 'GitHub Flavored Markdown' similarly cause offense?
- Ajedi32 10y agoGitHub Flavored Markdown has been a thing for a while. The only difference is that now they have a formal spec for it. Also, CommonMark failed? News to me. Last I heard it was still under active development, years after the drama with Gruber.
- criddell 10y agoIIRC, their first name choice was Standard Markdown. I don't blame Gruber for being upset at that.
- forsaken 10y agoThis is great -- lack of a standard that was actually used (unlike CommonMark) was one of my main issues with Markdown (http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/ http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-f...) -- It's really great to see GitHub leading in this department, and it gives me hope that one day we might actually have Markdown that is portable between implementations.
- SEJeff 10y agoPerhaps you missed Jeff Atwood (codinghorror)'s standardized markdown spec, which is about as close as you'll get: http://commonmark.org/ http://commonmark.org/
- forsaken 10y agoYea, I mention commonmark in the post, and referred to it in the "standard that was used" part -- commonmark is great, but wasn't widely adopted. Updated my original post to be more clear.
- zellyn 10y agoThis is actually very closely based on CommonMark, according to the article.
- jotux 10y agoThe github spec is literally CommonMark with extensions. https://github.github.com/gfm/ https://github.github.com/gfm/ http://spec.commonmark.org/0.27/ http://spec.commonmark.org/0.27/
- jorams 10y agoIt's odd how neither this post, nor the spec, nor GitHub's "Mastering Markdown" help page[1], nor the more complete "Basic writing and formatting syntax" page[2], mentions the fact that GitHub treats every newline as a hard break. CommonMark contains this little sentence to work around its specified behavior, which is left untouched in the GFM spec: > A renderer may also provide an option to render soft line breaks as hard line breaks. I'd say whether or not it does this is a rather important thing to mention. When I write Markdown documents for GitHub I have to change my editor settings, only because of this. [1]: https://guides.github.com/features/mastering-markdown/ https://guides.github.com/features/mastering-markdown/ [2]: https://help.github.com/articles/basic-writing-and-formatting-syntax/ https://help.github.com/articles/basic-writing-and-formattin...
- deleted 10y ago[deleted]
- y0ghur7_xxx 10y ago> It's odd how neither this post, nor the spec, nor GitHub's "Mastering Markdown" help page[1], nor the more complete "Basic writing and formatting syntax" page[2], mentions the fact that GitHub treats every newline as a hard break. Well, actually it does say that "Hard line breaks are for separating inline content within a block." https://github.github.com/gfm/#hard-line-break https://github.github.com/gfm/#hard-line-break So two spaces at the end of the line for a <br>, and an empty line for <p>.
- dreamcompiler 10y agoThis is great news! Does anybody have a recommendation for a Javascript parser for Formal GFM? (I know there are a million JS MD parsers; I'm looking for a good one that will let me serve GFM docs over HTTP and render them on the browser.)
- steveklabnik 10y agohttps://www.npmjs.com/package/marky-markdown https://www.npmjs.com/package/marky-markdown
- dreamcompiler 10y agoLooks good. Thanks.
- harmonyinfotech 10y agoIs it ok if I promote my domain here? I read the guidelines but it doesn't mention anything regarding self promotion. Sorry if it ain't appropriate but anyone looking for a relevant domain (markdown.in) please get in touch or any suggestion if it is better to develop it.
- erlend_sh 10y agoGitHub devs & Markdown enthusiasts at large, please consider contributing some brainpower to these last remaining issues that are blocking the v1.0 release of CommonMark: https://talk.commonmark.org/t/issues-we-must-resolve-before-1-0-release-8-remaining/1287 https://talk.commonmark.org/t/issues-we-must-resolve-before-...
- rcarmo 10y agoI have to wonder why this isn't done in the form of a context-free grammar, like Hitman[0] uses. Specs in English are still too vague for my liking. https://github.com/chameco/Hitman https://github.com/chameco/Hitman
- daigoba66 10y agoIs it even possible to define a context-free grammar for markdown?
- jws 10y agoIt is not, and not just because of a few idiosyncrasies like C which require context. Fundamentally, markdown was specified as some pattern matching and English description. The original specification was not done thinking of productions and grammar rules, and you typically don't get there by accident. See http://roopc.net/posts/2014/markdown-cfg/ http://roopc.net/posts/2014/markdown-cfg/ for a detailed exposition of how the '*' character in markdown is sufficient to ruin any chance of a CFG. I have sometimes pondered how to make a markdown-like language with a simple production based grammar. I have not succeeded and would appreciate any pointers. The criteria being that is has to have something like the minimal intrusion into the prose of markdown.
- nerdponx 10y agoIs there some kind of more general grammar that can encode the Markdown spec?
- eslaught 10y agoThere was some discussion of this on the CommonMark forums shortly after the initial release of CommonMark: https://talk.commonmark.org/t/commonmark-formal-grammar/46 https://talk.commonmark.org/t/commonmark-formal-grammar/46 See in particular these comments by maradydd: https://talk.commonmark.org/t/commonmark-formal-grammar/46/17 https://talk.commonmark.org/t/commonmark-formal-grammar/46/1... https://talk.commonmark.org/t/commonmark-formal-grammar/46/22 https://talk.commonmark.org/t/commonmark-formal-grammar/46/2... https://talk.commonmark.org/t/commonmark-formal-grammar/46/23 https://talk.commonmark.org/t/commonmark-formal-grammar/46/2... I'm not sure they ever came to a conclusive answer (at least on this thread). Edit: Here is JGM himself saying he doesn't know: https://talk.commonmark.org/t/commonmark-formal-grammar/46/33 https://talk.commonmark.org/t/commonmark-formal-grammar/46/3...
- strikedout 10y agoWhy no ~~strike out~~ in spec?
- kivikakk 10y agoRight here: https://github.github.com/gfm/#strikethrough-extension- https://github.github.com/gfm/#strikethrough-extension- :)
- oneeyedpigeon 10y agoIs their no corresponding equivalent of INS? I would have thought something like +new text+ could be used...
- flippyhead 10y agoJeesh, about time!
- patrec 10y agoNow if only org-mode could define a sane, parsable format.
- alphapapa 10y agoWhat do you mean?
- tomcam 10y agoweb2py handled all of these issues and made its markup language extensible with its markmin specification: http://www.web2py.com/init/static/markmin.html http://www.web2py.com/init/static/markmin.html
- IgorPartola 10y agoAt the risk of starting a mini-flame war, is RST a more cohesive format? If one was to pick one of the two formats to start using for personal documentation, which format should one choose?
- coddingtonbear 10y agoFor personal documentation (assuming you mean notes): follow your heart. Personally, though, I wouldn't use RST for any non-python public documentation at this point, but for my personal notes, it's hard to beat the extensibility of RST.
- mdaniel 10y agoI enjoyed this article http://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/ http://eli.thegreenplace.net/2017/restructuredtext-vs-markdo... and since the article didn't provide supporting evidence for the Linux/OpenCV/LLVM assertion: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html and http://docs.opencv.org/2.4/doc/tutorials/introduction/how_to_write_a_tutorial/how_to_write_a_tutorial.html http://docs.opencv.org/2.4/doc/tutorials/introduction/how_to... and https://github.com/llvm-mirror/llvm/blob/master/docs/index.rst https://github.com/llvm-mirror/llvm/blob/master/docs/index.r... respectively I do think rST is waaay more expressive, but I also recognize that in many of the instances one would want to use markup in a chat or PR situation, the expressiveness likely wouldn't be well received if the trade-off is verbosity. This is something in life that I file away with competing regex standards: my brain just has to switch languages based on the app in which I'm typing (between markdown, pseudo-markdown (ahem, Slack), org-mode, rST, etc).
- jostmey 10y agoHTML used to serve as a simple way to format a document. Now HTML is too complex for that purpose. Introduce markdown. In ten years, markdown will be too complex for formatting documents. I am big of markdown in case I didn't make that clear. I love it
- hawkice 10y agoIt wasn't an issue of simplicity, it was about HTML being extremely hard to sanitize so it isn't turing complete. Having formatting (that can still line up with your sites styles) while knowing you can't get script injection is pretty useful.
- wtetzner 10y agoI don't think it's that HTML is too complex. It's more that Markdown allows documents to be marked up in a way that "natural" and easy to read if you're reading the plain text version of it.
- Siecje 10y agoWhat's wrong with http://www.vfmd.org/ http://www.vfmd.org/ ???
- charonn0 10y agoSo that's why my project wikis have suddenly stopped rendering markdown properly. I've been trying to figure out WTF was going on since yesterday!