Markdown is powerful because it allows a document to be written once then exported in several different formats and styles.  Some of the text editors listed in the Authoring section of this page feature built-in Markdown converters though stand-alone converters to exist.  Many stand-alone Markdown converters have no graphic user interface.  This unfortunate fact makes converting Markdown documents difficult.  OU Libraries realizing this has developed a web interface to what is perhaps the most powerful Markdown converter, Pandoc. 

Use

In order to use OU Libraries' Markdown Converter, a user needs to upload a markdown document ending in the file extension ".md" to the converter, select the desired export file types, and one of the provided stylesheets.  Users may also provide their own stylesheets (CSS files) in which they may specify their own look-and-feel to be applied to their document.  If uploading more than one file, bundle them all into a .zip archive and upload the archive itself.  Examples of file structures that can be uploaded to the converter are shown below:

Single Markdown File:

whole_book.md

A Few Markdown Files and a stylesheet:

book.zip/
├───chapter1.md
├───chapter2.md
├───chapter3.md
├───stylesheet.css

Multiple Markdown Files, Images, and a Stylesheet:

book.zip/
├───chapter1.md
├───chapter2.md
├───chapter3.md
├───chapter4.md
├───stylesheet.css
├───images/
│   ├───image1.jpg
│   └───image2.jpg
│   └───image3.jpg
...

Flavors

There are many different Markdown implementations.  CommonMark (CommonMark Tutorial) aims to include the best features of all the Markdown flavors while being true to the original Markdown philosophy outlined by its creator John Gruber.

Editors

Dillinger is an online Markdown editor and live-previewer that can sync with online file sharing services such as Dropbox, Github, Google Drive, and One Drive. 

Atom full-featured is text editor application.  It features syntax highlighting, version control integration, and various plugins that allow users to extend its functionality. 

• Markdown Preview Package is an add-on package for Atom that renders a preview of markdown in a side-by-side fashion
• Markdown Preview Enhanced is an add-on package for Atom that renders a preview of markdown in a side-by-side fashion.  It also features MathJax support for writing equations in LaTeX markup.  It also has the ability to save Markdown documents as PDFs, HTML, and other file formats.

TextEdit is the text editor that comes installed on Apple desktop and laptop computers. It does not have the ability to render previews or Markdown, but if you are comfortable with the Markdown syntax it might be the distraction-free editor you are looking for.

Notepad is the text editor that comes installed on Windows desktop and laptop computers. It does not have the ability to render previews or Markdown, but if you are comfortable with the Markdown syntax it might be the distraction-free editor you are looking for.

StackEdit is an online Markdown editor that can sync with online file sharing services such as Dropbox and Google Drive.  Note that it only exports Markdown and HTML files.  PDFs can only be generated with a subscription.

Best Practices

Markdown is has a very loose syntax. -meaning that you won't receive error messages if you happen to type mistype the syntax, it simply will not render as you intend.  This makes it important to adhere to a few best practices especially if you are collaborating with other people on a document. 

File Extensions

Because Markdown files are plain text files they can be written in any plain text editor such as those listed in the Editors section.  It also means that they can be saved with any extension including .txt, .csv., and .dat.  These are all common plain text file extensions that hint at what can be expected to be found in those files.  Markdown documents should be saved with the extension ".md" indicating what they contain. 

Headings

Writing Markdown collaboratively is easy because there is no formatting.  This means that there need not be any communication about how large fonts should be, or whether or not headings should be bold or underlined.  Formatting is separate from content.  The content of a Markdown document is completely contained within a .md file and its style is applied when the Markdown file is converted into a consumable format ( HTML, PDF, or ePub) in the form of a cascading style sheet. 

There is; however, on thing that collaborating authors out to be on the same page about and that is heading levels.  Take, for example the case that each author is writing a chapter of a book where each chapter contains a number of sections and subsections.  These should each take on a unique style that should be agreed to by all authors.  My suggestion would be as follows:

• # Book Title
• ## Chapter Titles
• ### Section Headings
• #### Section Sub-Headings
• ##### Section Sub-Sub-Headings

Note that all heading levels (# - ######) are distinctly different from any bold or italicized text.  That is to say that bold text should never be used in place of ### - ###### when a heading is intended, for example.  Bold and italicized text should exclusively be used to emphasize normal paragraph text in order to preserve its ability to be uniquely styled and addressed across a document.