previewdocs :: index

Welcome to previewdocs

Viewdocs is Read the Docs meets for simple project documentation. It renders Markdown from your repository's docs directory as simple static pages.

previewdocs is a work in progress CLI tool that helps you preview changes to your documentation before pushing the code back to your repository.


Download the latest released version for your platform from GitHub, place it somewhere on your PATH and make it executable.

If you think you'll reach GitHub's Rate Limit of 60 requests per hour while working on your docs, please create a GitHub access token and place the token on $HOME/.previewdocsrc or set it as the the ACCESS_TOKEN environmetal variable.

Getting Started

If you are new to Viewdocs, just make a docs directory in your GitHub project repository and put an file in there to get started.

Then run previewdocs from the project's root and browse to:


Any other Markdown files in your docs directory are available as a subpath, including files in directories. You can update pages and hit F5 to see the changes as you go instead of pushing the code back to the GitHub repository and waiting for Viewdocs cache to expire.

This page is an example of what documentation will look like by default. Here is another example page. The source for these pages are in the docs directory of the project.

Custom layouts

Viewdocs supports custom layouts for your docs. You can make your own docs/template.html based on the default viewdocs template and your pages will be rendered with that template.

More information

I highly recommend you read the source of this app. It's less than 200 lines of Go. If you want to hack on previewdocs, check this out.

Fábio Rehm