Writing in Markdown
How to write documents using Markdown syntax
Markdown is a lightweight markup language, which is often used to add formatting to documentation. This sets it apart from other text formats like Microsoft Word, which are edited using a “What You See Is What You Get” (WYSIWYG) method. When editing a Word Document, changes appear instantly, as they would appear in the final document. Conversely, Markdown is a “What You See is What You Mean” (WYSIWYM) format – formatting is specified using a special syntax. When editing Markdown, you might see something like this:
# Top-Level Heading
## Level 2 (Sub-)Heading
### Level 3 Heading
Some text.
*italic*
**bold**
***italic bold***
We see that markdown can be used to specify headings and subheadings, change the appearance of text, and to include images in your document. Other software, e.g., Github and GitLab can interpret this syntax, and display it as formatted text. This document can also be converted to many other formats, including Microsoft Word, PDF, or HTML, and many of these formats can also be converted back into Markdown.
Although this approach might seem inconvenient at first, Markdown has one major advantage: unlike WYSIWYG formats like Microsoft Word, Markdown files are plain text files. This means they can be edited with any text editor, so you (and your collaborators!) need not rely on any proprietary tools to edit documentation. Plain text files are also much easier to track using version control systems like Git.
For more information on the features of Markdown and how to use them, see any of the numerous online tutorials, e.g., https://www.markdownguide.org/.
P.S. There is no shame in having a Markdown cheat-sheet pinned to your virtual or physical wall 😉