Griffel is derived from tripit/slate with the biggest difference being that it fetches documentation markdown from GitHub repos based on whatever the user has access to.
The idea behind everything is to store documentation close to the code (preferably inside the code repositories to avoid divergence) while at the same offer a beautiful central documentation hub.
- User authenticates with his or her GitHub account...
- ...Griffel fetches the documentations that the user has access to from the configured GitHub repositories...
- ...and compiles everything into a uniformed visually appealing documentation view.
- Super crisp UI thanks to the beautiful people over at tripit/slate 🙇
- Multi repository support, meaning that one can easily pull in API documentations from various code repositories to a central documentation hub.
- Documentation written in Markdown.
- Per-user access control. Users will only see documentation for the repositories he or she has access to.
- Works with both private and public repositories.
- GitHub Enterprise support.
Griffel is designed to run on Heroku but can easily be deployed wherever.
$ git clone git://github.com/plan3/griffel.git
$ cd griffel
$ npm install
Griffel is Twelve-factor compatible and therefore reads its configuration from the environment.
COOKIE_SECRET- Used to sign session cookies.GH_CALLBACK_URL- GitHub callback URL used during authentication.- Example:
http://example.com/auth/callback
- Example:
GH_CLIENT_ID- A client ID for your GitHub Application.- Wat? Have a look at Basics of Authentication
GH_CLIENT_SECRET- A client secret for your GitHub Application.GH_REPOS- A comma separated list with repos to fetch documentation from.- Example:
hnrc:griffel-demo-kittn,hnrc:griffel-demo-doges
- Example:
DOC_PATH- A path to wherever you've placed your documentation markdown. (Default:api-spec.md)ACCESS_PRIVATE_REPOS- Set to an arbitrary value to access private repositories.GH_HOST- The hostname of your GitHub instance if you're running GitHub Enterprise.GH_API_PATH_PREFIX- Something like/api/v3is usually needed for GitHub Enterprise installations.
$ node app.js
or if you're into Heroku and foreman:
$ foreman start
Pull requests are always welcome 🍻