How to view markdown files

Three methods:

Read the markdown file as plain text.
Render the markdown file as HTML.
Render the markdown file as man.

Plain text

Markdown source files are quite readable, as they have to be for editing. The main drawback is word-wrapping.

Some text editors, including emacs and nano, have a keypress which reformats a paragraph of text, removing the existing newline characters and inserting fresh newline characters so as to make every line a bit shorter than 80 characters (or whatever you have configured the width to be). Firefox displays text files in this way, starting a new line of text only where it sees a newline character.

A more modern but different approach is used by other editors, including gedit, kate and Nodepad++, which is to display long lines of text on multiple lines, even though they contain no newline characters. This style is easier to edit, as you don’t have to maintain the newline characters, and it is more compatible, as the text wrapping automatically adjusts to the width of the editor window.

Both kinds of text file are acceptable as input to markdown, so people write in both styles (this file uses the latter). An editor which wraps automatically will display both kinds of file acceptably, but an editor which reformats paragraphs is needed if you want to edit a file with explicit line breaks.

HTML

The “markdown” command outputs a fragment of HTML. To make a valid HTML file that you can view in a web browser, you need to wrap it in some boiler plate. The following is sufficient to make it formally correct and reasonably pretty:

<html>
<head>
    <meta charset="UTF-8">
    <title>Example of how to present Markdown-generated HTML</title>
    <link href="http://mincss.com/entireframework.min.css" rel="stylesheet" type="text/css" />
</head>
<body>
    <div class="container">
        <p>Paste the output of <code>markdown</code> here.</p>
        <p>The stylesheet is from <a href="http://mincss.com/download.html">mincss</a>.</p>
    </div>
</body>

As the snippet explains, it relies on a third-party CSS stylesheet. You may wish to make a local copy of it (and to edit the <link/> accordingly).

Man

The “pandoc” command can read Markdown and write man format. The latter can be rendered by the “groff” command with margins and using terminal control codes for bold and italic text, and the result can be navigated and searched using “less”. Here is a suitable shell pipeline that I found on Stack Overflow:

pandoc -s -f markdown -t man my_file.md |groff -T utf8 -man |less