I’ve been writing various lengthy documents for GitHub repositories recently, and as I push them to GitHub, and then view them in the browser, there’s almost always something wrong with the layout resulting in additional commits or amends/forced updates which I would rather avoid. I was initially using MacDown to edit/preview Markdown, but its rendering of GitHub Flavored Markdown (GFM) was way off. There had a to be a better way, and there is! I found two solutions that work reasonably well: the first one is Node-based vmd for general use (it watches the given file, and thus works with any editor), and the second is a set of plugins for Sublime Text 3. The former is now my choice for offline GFM previewing (such as on a plane), while the latter is my preferred choice because 1) Sublime Text 3 is already my go-to editor, 2) the Sublime Text plugins provide incredibly handy macros for, and context-highlighting of the Markdown being edited and, most importantly 3) the GFM is rendered through the GitHub API, ensuring that the rendered output matches the way GitHub renders it 100%. Both
vmd and the Sublime Text solution work on macOS, Windows, and Linux Desktop.
Some other options that I looked at included Grip (a cool idea, but it kept crashing on me), or Atom‘s GFM preview (which, even with the right extensions installed, wasn’t accurately GFM, which is strange considering that Atom is made by GitHub; if you know how to make Atom render GFM through the GitHub API, please comment this article).
vmd. It’s easy to set up, simply first install Node.js on your platform, then add
npm as a global:
npm install -g vmd
Now simply point
vmd to the file you’re editing, and it gets re-rendered every time the file is saved as long as
vmd is running.
That’s all. You can use any editor to edit the file.
However, if you’re using Sublime Text 3, give the following a try; it makes Markdown editing outright fun. The following instructions are for ST3.
- Install Sublime package manager if it’s not yet installed. Then restart Sublime.
- Install the following packages with the Package Manager:
Ctrl-Shift-p [Win] / Cmd-Shift-p [macOS] > Package Control: Install Package
- Install monokaiC theme (read the installation instructions on its GitHub page).The target location depends on the platform, see this StackOverflow answer for details, but use the User subdir under the directory listed for your platform.
- In Markdown Preview User Settings:
Preferences > Package Settings > Markdown Preview > Settings — User
** Get the
git_oauth_tokenfrom GitHub. Log in to your GitHub account, then:
Settings > Developer Settings > Personal Access Tokens, or use generatetoken.sh script. No scope permissions are required for a token for it to be valid for Markdown rendering. Note that without a token set you’re limited to about 60 renders per hour, while with the token set you can make 5000 requests per hour (which you’ll never hit, since the re-render only occurs on file save).
** Make sure you have a comma at the end of each line, except the last parameter line in the settings
- In Markdown Preview User Settings:
- In Markdown Editing User Settings for GFM:
Preferences > Package Settings > Markdown Editing > Markdown GFM Settings — User
- In Key bindings
Preferences > Key Bindings — User
Ctrl-Shift-p [Win] / Cmd-Shift-p [macOS] > Live Reload: Enable/Disable Plugins > Enable Simple ReloadYou need to reactivate Simple Reload like this whenever you restart Sublime, and want to use the auto-reload.
All set! Open an existing markdown (.md) file, or start a new file and save it with
.md extension. Then hit
alt-m for GitHub-rendered preview, or
alt-l for locally rendered (but less accurate for GFM) Markdown preview. When you make changes and save the file, the preview gets automatically refreshed in your browser using the originally selected method (i.e. GitHub API or local).
Be sure to read the MarkdownEditing documentation for awesomely useful keyboard macros and other support for Markdown! This will also give you syntax highlighting in fenced code blocks when you postfix the first triple-backtick with supported language identifier, like so:
Happy GitHub Markdown editing!
Update 2018-03-02: The
git_oauth_token must be set in Markdown Editing package settings, not in global Sublime settings. This correction has been reflected in the above instructions.