Are you using Apiary for documenting your API and GitHub for storing your code base? Apiary has a really cool feature that will keep your markdown stored inside of your git repository and update the Apiary version every time you push a change to Github. To set this up, go to the Settings section of your Apiary account by this icon on the top bar:

Then scroll to the bottom of the page and you will see a “Link Your GitHub Repository” section:

Check the box to grant access to the private repositories (if you’re connecting to a private one) and then click Connect to GitHub. Once you have finished the authorization process you will be back on the same page in Apiary, but it will look like this:

Click on the repository you want to connect it to and click Go. Apiary will add a file to the master branch of the repository named apiary.apib. If you update the Apiary documentation on their website and save it, it will do a git commit to keep the repository up to date. Even better, if you commit changes to the Apiary markdown inside of your repository and push it to GitHub, the latest documentation will be reflected in Apiary! This makes it very convenient to keep your Apiary in lock step with your code and you can even apply branching and tagging to it now.

Now for the Coup d’état: Integration with your README.md!

As you probably know, GitHub supports a special file in the root of the repo called README.md. This is a MarkDown file that almost everybody uses to display the documentation for the repository. GitHub renders it below the root file listing on the repository homepage. Since the markdown dialects for Apiary and GitHub are reasonably similar, it would be really awesome if your Apiary documentation showed up here!

Luckily for us, git supports symlinks. Check out your repository and get rid of your existing README.md file (if any). I actually moved mine to INSTALL.md since it was more appropriate for installation than primary documentation. Now run the following from your command line (Linux and Mac Only – Sorry Windows folks, I have no clue if Windows has some version of symlinks yet):

ln -s apiary.apib README.md
git add README.md
git commit -m "Symlinking README.md to apiary.apib thanks to demar.is"
git push origin master

Voila! Other than the FORMAT: 1A line at the top, this looks great!