_drafts

Writing in Markdown

Markdown is a quick and simple way to write formatted documents in plaintext. It is intuitive and easy to read, but is designed to convert to HTML for easy web publishing. Writing in plaintext rather than proprietary formats such as Word has many advantages:

  • simple - don’t waste time in complex and frustrating formatting in Word that will be deleted by publishers anyway. This keeps your distractions to a minimum.
  • sharable - any device can open and read plaintext, no special software needed, unlike Word.
  • preservable - markdown is plaintext which is easy for digital preservation, unlike Word.
  • version controllable - you can use the full power of Git or other version control systems, unlike Word.

GitHub Markdown

Markdown was originally developed by Daring Fireball. However, other “flavors” of md have developed. The most popular is GitHub markdown flavor, since it can be used anywhere on GitHub.

Here are some tutorials:

Markdown editors

Markdown is plain text, it’s sort of like source code for your document. You can write it in any application that supports plain text, i.e. a text editor. When working with code you should have a good text editor.

For basic editing, Windows Notepad++, Mac TextEdit, or Linux Gedit are sufficient (note: you can use Windows Notepad, but it does not handle UTF-8 encoding or UNIX line endings that are standard for most cross platform applications). However, more advanced code editors often have plugins or features to make it easier with previews of your document. Checkout Visual Studio Code (use shortcut Ctrl+Shift+V to preview) or Atom.

If you want a more fully featured visual writing environment, there are also applications devoted specifically to writing in Markdown. These apps will have previews, GUI controls, and automatic export options.

Web-based:

Stand alone apps:

  • Remarkable - code / preview split screen.
  • Typora - live preview writing focused slick new app.

Rendering Markdown

Markdown is human readable as plain text–it is intuitive like writing an email. However, it is designed to render as HTML. Markdown compilers are built in to many applications (like the editors above) to generate formatted versions such as HTML, .docx, or PDF.

One option is Pandoc, a command line utility to translate between many formats and generate new output versions, such as PDFs (via LaTex). Check my note Pandoc for PDFs or the Sustainable Authorship in Plain Text tutorial.