On Writing Markdown

• Markdown Home Daring Fireball by John Gruber 17 Dec 2004.

  Markdown is a text-to-HTML conversion tool for web writers.

  Thus, “Markdown” is two things:

  1. a plain text formatting syntax; you can view the Markdown source for the article text on this page here: https://daringfireball.net/projects/markdown/index.text¹.

     The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible.

  2. (2) a software tool, written in Perl, that converts the plain text formatting to HTML

     (click to download ==> ‘Markdown.pl’)².

     By default, Markdown produces XHTML output for tags with empty elements:

     <br />
     

• CommonMark Spec Current Version 0.30 (2021-06-19) by John MacFarlane

  John Gruber’s canonical description of Markdown’s syntax does not specify the syntax unambiguously. ‘Markdown.pl’ was quite buggy, and gave manifestly bad results in many cases, so it was not a satisfactory replacement for a spec. Because there is no unambiguous spec, implementations have diverged considerably. As a result, users are often surprised to find that a document that renders one way on one system (say, a GitHub wiki) renders differently on another (say, converting to docbook using pandoc).

  The CommonMark specification attempts to specify Markdown syntax unambiguously. The examples are intended to double as conformance tests. An accompanying script spec_tests.py can be used to run the tests against any Markdown program:

  python test/spec_tests.py --spec spec.txt --program PROGRAM
  

• GitHub Flavored Markdown Spec

  ‘GitHub Flavored Markdown’, often shortened as ‘GFM’, is the dialect of Markdown that is currently supported for user content on GitHub.com and GitHub Enterprise.

  ‘GitHub-flavored Markdown’ is based upon the CommonMark Spec by John MacFarlane. This formal specification, based on the CommonMark Spec, defines the syntax and semantics of this dialect. GFM is a strict superset of CommonMark. All the features which are supported in GitHub user content and that are not specified on the original CommonMark Spec are hence known as extensions, and highlighted as such.

  Some features of ‘GitHub Flavored Markdown’ are only available in the descriptions and comments of Issues and Pull Requests. These include ‘@mentions’ as well as references to SHA-1 hashes, Issues, and Pull Requests. Task Lists are also available in Gist comments and in Gist Markdown files.

  • Some Extensions
    • Syntax highlighting
    • Task Lists
    • Tables
    • SHA references
    • Issue references within a repository
    • Username ‘@mentions’
    • Automatic linking for URLs
    • Strikethrough
    • Emoji
• Mastering Markdown

  This is a GitHub Guide, fairly simple in nature.

• Writing on GitHub

  This is also a GitHub Guide, more extensive and advanced in nature than Mastering Markdown.

• Markdown Syntax

  This is a GitHub Cheatsheet-style guide.

• Markdown Cheatsheet

  This is intended as a quick reference and showcase.

• GitHub REST API v3 — Markdown