github-markdown-preview

Local Github Markdown Preview

Use your favorite editor plus the usual edit/refresh cycle to quickly write and polish your markdown for Github.

This program marries html-pipeline with the Listen file watcher to provide a high-fidelity preview (in your local browser, automatically updating on edit) of how Github will render your markdown.

Installation

gem install github-markdown-preview

Usage

Generate a preview of how Github renders markdown files in a repository:

$ github-markdown-preview <path/to/markdown/file.md> # writes <path/to/markdown/file.md.html>

• The .html preview is written beside your .md file so that you can validate relative links locally
• The .html preview is deleted when the script exits

Comment mode

Use the -c switch to generate a preview of how Github renders comments/issues, which differs from repository markdown files in a few ways:

• newlines are rendered as hard breaks
• @mentions are linked to the user's home page
• Note: auto-linked references are not rendered as links. See #17

$ github-markdown-preview -c <path/to/comment/draft.md> # writes <path/to/comment/draft.md.html>

Enable syntax highlighting for code blocks

To enable syntax highlighting for code blocks, you will need to install github-linguist:

gem install github-linguist -v 3.3.1 # 3.3.1 is required
gem install rugged -v 0.23.0 # undeclared dependency of linguist

Note that this install will fail unless your system meets the requirements needed to build its native extensions:

• You will to either brew install icu4c or apt-get install libicu-dev
• On Mac, you will need to have XCode installed (seems like a full install is required, not just the Command Line Tools)

Code

Here's a sample file demonstrating how to call github-markdown-preview from your own code:

require 'github-markdown-preview'

# create a preview, which writes the source_file.md.html file to disk
preview = GithubMarkdownPreview::HtmlPreview.new('source_file.md')

# you can also configure your preview with a couple of options
preview = GithubMarkdownPreview::HtmlPreview.new('source_file.md', {
    :delete_on_exit => true, # delete the preview when the program exits
    :comment_mode => true, # render using the rules for Github comments/issues
    :preview_file => 'custom_preview_file.html' # write preview to the given filename,
                                                # rather than the default 'source_file.md.html'
})

# access the preview information
preview.source_file # returns 'source_file.md'
preview.preview_file # returns 'source_file.md.html'

# explicitly update the preview file from the source
preview.update

# watch the source file and update the preview on change
preview.watch # non-blocking watch
preview.watch! # blocking watch

# add a callback to be fired on update; add multiple listeners by calling again
preview.update { puts 'Preview updated!' }

# stop watching the file (only applies to non-blocking watch method)
preview.end_watch

# delete the preview file from disk
preview.delete

Development

$ bundle install
$ rake test

Alternatively, to test with optional dependencies

$ BUNDLE_GEMFILE=Gemfile.optional bundle install
$ BUNDLE_GEMFILE=Gemfile.optional rake test

To run your development copy of the main script without installing it

$ bundle exec bin/github-markdown-preview

To install the your development copy to your system

$ rake install

Contributing

Contributions welcome!