Documentation Site Guide | Using Markdown

Markdown Basics

Markdown is a lightweight Markup language. A Markup language is an annotation system for text that makes that text machine-readable (eg. XML and HTML). Markdown is designed to be easy to read, write, and edit using a limited set of punctuation characters to annotate the text. It is a plain text format; it does not specify color, font, or other style elements. The documentation platform requires that documentation be created in or converted to Markdown. This contributes to documentation portability, intentional and consistent formatting for web content, and easily converts to HTML and other formats.

Learn Markdown: Guides and Resources

  1. Mastering Markdown GitHub Guide. Quick reference for Markdown basics.
  2. Ghost Blogpost. How to Write Faster, Better & Longer: The Ultimate Guide to Markdown
  3. CommonMark specification with quick guide and tutorial.
  4. Markdown tutorial from Garen Torikian.

Convert and Edit Files

Tools that will convert files from DOCX to Markdown, or between Markdown and other formats:

  1. Dillinger. An in-browser converter that displays Markdown in the left window and HTML on the right.
  2. Devotter. An in-browser converter that allows users to upload files and convert documents between multiple formats.
  3. Markdown Converter from the University of Oklahoma Libraries. In-browser tool to convert from Markdown to DOCX, PDF, EPUB, HTML.
  4. Pandoc. A command-line document converter.
  5. Writage. A Microsoft Word plugin that allows DOCX files to be saved as Markdown. Download the plugin, open the document in Microsoft Word, Save As, and choose Markdown from the Save As Type dropdown menu.

Edit Markdown Files in a Text Editor

It is possible to compose Markdown content using an in-browser editor like StackEdit. This can be helpful to learn the Markdown syntax. To export work as a .md file in StackEdit, choose “export to disc” in menu in upper right corner of screen.

Install a text editor like Atom to create, view, and edit Markdown files (.md). Text editors often have preview options such as the Markdown Preview plugin in Atom.