Skip to content

Learn Documenting / Reference - Markdown

Markdown files are simple text files with embedded formatting markup text. This documentation is created using Markdown and the MkDocs software.

Markdown Overview

See:

Benefits of Markdown

  1. Markdown files are simple text files and can be edited with a text editor.
  2. Markdown files can often be understood when edited with a text editor, even without formatting output. Therefore, Markdown files are similar to README text files.
  3. Markdown can be converted to HTML and therefore can replace more complex HTML in many applications. For example, Mkdocs source content is written in Markdown and gets converted to static HTML websites.
  4. Many tools now recognize Markdown and are migrating to its use as a preferred or default option. For example, Markdown files in a GitHub repository will automatically be formatted and displayed.
  5. Markdown files are simple and people require little training to attain proficiency using Markdown.
  6. Versions of Markdown files can be easily tracked in a version control system such as Git. Differences between versions can be easily pinpointed, compared to binary files such as Word and PDF that are essentially "blobs" of encoded text.
  7. Because Markdown is an open standard, there are many open source and commercial software tools.

Limitations of Markdown

  1. Formatting in Markdown files is simple by design and may not meet all formatting needs. Complex formatting such as equations requires additional tools and/or formatting tricks such as saving to an image or embedding raw HTML into the Markdown. This is a topic of ongoing discussion.
  2. People may not be familiar with Markdown or related software tools.
  3. Although Markdown files can be emailed, they are better suited for online collaborative platforms. This limitation may not be as much of a factor in circles where people are comfortable with Markdown.
  4. Markdown editors that show the formatted text parallel to the input may not be available. Such tools are becoming more common and therefore this limitation will diminish over time.

When to Use Markdown

The following are recommendations for when to use Markdown:

  1. If the overall environment favors Markdown, such as Git repositories.
  2. When creating navigable, interactive static websites such as software manuals - MkDocs is a good option.
  3. When an upgrade to standard text README files is appropriate, in particular when files can be moved to a version control system such as Git/GitHub.

When Not to Use Markdown

  1. When a traditional memo/report document is needed - Word/PDF are probably better in this case.

Markdown Tools