Markdown:Viewing

Viewing markdown content

Atom preview

The atom text editor has a built in viewer accessed from Packages menu Markdown Preview that displays content fairly close to the way it would be shown when stored on github, and viewed using github flavour markdown. This applies both to actual documents that will be shown on wcrsyyc.github.io, and to pages in the wiki. There are differences though. Some (extended) markdown features work one place but not the other. Tables do not work for the wiki. The final check has to always be to review the content on github, after pasting into the wiki page, or pushing the (changed) content to github.

Firefox Markdown Viewer Webext

The Markdown Viewer Webext addon allows markdown pages to be viewed in the Firefox web browser. This works both for markdown pages stored on the web, and files on your computers local storage. That can be installed through the Firefox addon manager (search for markdown), or by browsing to the addon web page.

Installing the addon is not quite enough to get it to work. At least on Fedora. By default, markdown files do not have a MIME type associated with them. Because of that, Firefox does not understand what to do with them. Before the plugin gets a chance to handle them, Firefox cancels the display, and offers to save the file. To get around that, a MIME type needs to be defined at the operating system level for markdown files. On Fedora, that is as simple as adding a text-markdown.xml file into the directory $HOME/.local/share/mime/packages with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
  <mime-type type="text/plain">
    <comment>markdown document</comment>
    <glob pattern="*.md"/>
    <glob pattern="*.mkd"/>
    <glob pattern="*.markdown"/>
  </mime-type>
</mime-info>

The patterns are the rules to use to tell when a file should be treated as markdown. Or actually as text/plain, which the addon then gets chance to process as markdown.

It used to be that the Firefox Markdown Viewer Webext addon could not handle unicode characters in local markdown file, unless the file had a BOM. The readme for Markdown Viewer Webext describes the cause, and points to a simple solution.

Summary: Firefox defaults to using the regional encoding defined for the operating system when opening local files. That can be changed by setting intl.charset.fallback.utf8_for_file to true in about:config. Now files with utf-8 content are displayed correctly.

Once the addon is displaying a file in Firefox, the standard browser tools can be use to print it, or print to file, to create a PDF version. The addon has the ability to provide custom css to tweak how the content is formatted. It does a good enough job out of the box that there is no incentive to tune it for github.

grip (GitHub Readme Instant Preview)

Another method to display local markdown files approximately the way they would look on github, is the grip application. This runs a small server on the local machine, and uses the github api to render the content locally. Because of that, it only works when an Internet connection is available. It does not store anything on github. It just uses the code there to convert the markdown to html for display. Since it uses the actual github code, it should do a very good job. I have found though that it handles a few borderline cases differently than github. However, if it looks right using grip, it is very likely to be close to what github will show. Within the limitations of where on github the content will end up. grip will display gfm tables, but if that is pasted into a wiki page, the table may show as only text, not a table. The wiki pages are a little bit fussier than grip, which in turn is a little fussier than the what github uses to display readme files and content on github.io.

If you already have python and pip installed, getting this is as simple as (from a terminal window)

pip install grip

On OS X, you could also use Homebrew:

brew install grip

Once installed, cd to the directory where the markdown file(s) exist, and type grip -b «file» to open a new tab in the browse, displaying the specified markdown file. There are more options, but that is enough to get running. Use Ctrl+C in the text window to exit.

Grip is also useful while creating a markdown file. It watches for changes to the file, and automatically refreshes to show the updated content. This is not quite as interactive as using the Markdown Editor Firefox editor, but works with any browser, and (mostly) does a better job of showing what the content would like on github. Every time the markdown content is saved from the text editor, grip updates the display in the web browser. Don´t get too carried away with that though. The github api does some rate limiting. More than 60 refreshes per hour will cause the api to lock you out for awhile. If you need more than that, grip has some extended options to provide github signon details, which increases that limit considerably.

My testing says grip does not produce a perfect replica of github formatting. In addition to small formatting differences, the app running on github is more robust against certain types of errors. Not even really errors. Just minor differences in cases where the rules for markdown are not fully defined.

• github adds an extra title line at the top of github.io pages created from markdown, that is a link to the main github.io page for the repository. Grip puts a line showing the local file name instead.
• grip draws a box around what would be the page content on github, and the left/right margins seem to be bigger
• the second line of markdown content for a table is used to specify the the justification to use for the table columns. Symptoms say that, for github.io, if that line does not have enough columns, either the last actual entry is repeated, or a default value is used. With grip, if the first and second rows do not have the same number of column entries, the raw text is displayed instead of a table.
• if the header matches the justification columns, but later rows have more columns, grip does not display the additional columns. github does.
• a blank table row (a table row with only whitespace, like | |) is shown vertically compressed by grip, github shows it the same height as a row with short text strings
  • work around that by using | | instead. That forces a non-breaking space character, which return the row to full height. Inspecting the result of what github actually does shows that that is what it does. A non-breaking space character is automatically inserted in every blank cell of the table.