Markdown

A lot of the documentation we do for and within the WCRS repositories is done with markdown. This page, and those it links to, are intended to provide some assistance for working with markdown documents, locally on your computer, as well as on github, or other places.

From the wikipedia article:

Markdown is a lightweight markup language with plain text formatting syntax. … Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.

Editing pages in the github repository wikis (like this one) defaults to using Markdown syntax for formatting. Other options are available from the Edit mode dropdown. Using the buttons on the editing toolbar just insert the text of the markdown commands that would be used when creating markdown content manually.

Issues, pull requests, comments, and more on github support markdown formatting. Markdown has a basic set of features. As used on github, several extensions provide extra capabilities. Those extra features are available some places but not others. For example, tables can be added to repository readme files, and other content that will be displayed on github.io, but they are not available here in the wiki.

Since markdown starts as plain text, no knowledge of markdown syntax is needed to create content. Markdown just provides a way to enhance the content, to provide lists, code blocks, headers, italic, bold, clickable links and more. None of which is actually required.

Some starting references:

• Mastering Markdown
• writing on github
• gfm (Github Flavoured Markdown)