It is very common when uploading your repositories to GitHub to include a file called README.md with your repository. This file is usually written in GitHub Flavored Markdown, which is essentially traditional markdown with a few added features from GitHub. Markdown is a super simple, text-focused language that gives you easy ways to add lists, font formatting, blockquotes, code snippets, headers, and much more.

When working with multiple projects on GitHub, I've noticed that it is sometimes inconvenient that you cannot view the output of your markdown until your changes are pushed up to GitHub. If you make a mistake, or something is not formatted as you'd like, this can lead to unnecessary commits. To solve this issue, I've created a small Ruby gem called yield, that allows you to view the output of your markdown rendered by GitHub's Markdown API.

Installing the Gem

Installing the gem requires Ruby v1.9.3 or greater, so be sure to have that installed before the installation. To get started with yield, you can begin by running the following command to install the latest version:

gem install yield

This will install the yield gem, and will give you access to its executable.

Using Yield to Render Markdown

After installation, from any repository with a README.md file, issue the yield command to fire up the server and parse your markdown file:

yield
=* Yield is serving your markdown at http://localhost:4000/

This will start up a server instance using Thin, and open your browser to localhost:4000. You should see something in your browser similar to the following, which is the README.md file for the yield gem.

You can render markdown files that are not named README.md by specifying the name of the file as an argument to yield.

yield updates.md

This will render the contents of the updates.md file in the browser at localhost:4000.

Yield also supports relative URLs, so you can render markdown files just by navigating to their filename in the browser. For instance, the updates.md file can be viewed at localhost:4000/updates.md.

Finally, you can set the port for the server to start on by using the -p or --port option, shown below.

# Specify the port to serve on
yield -p 8080
=* Yield is serving your markdown at http://localhost:8080/

Check out the repository on GitHub for the latest updates and to view the source for the gem. This gem is still in development so many updates and improvements are likely to come.

Resources

yield homepage
yield source code on GitHub
Markdown Syntax Guide
GitHub Flavored Markdown
GitHub's Markdown API