Static site generators have been around for a while. They have a great number of use cases but why are they the right choice for developer.xappmedia.com?
Leverage Existing Workflow
Documentation is really no different from source code, at their core they are just stylized text files. Thus we decided to leverage the same workflow we use for developing features and apply it to updating the documentation.
- Clone the Documentation Repository
- Submit a pull request
- Peer Review
Easy to Deploy
Jekyll, our static site generator, makes it tremendously easy to compile the CSS, HTML templates, and markdown into a static site.
To build simply run:
$ jekyll build
Then to deploy to production, we leverage the AWS CLI
$ aws s3 sync
Using these commands, we setup continuous deploy on our build server so whenever we merge a pull request, the production site is instantly updated. Automating this process allows us to concentrate on the documentation and not have to worry about deploying.
We want the documentation to be easy to use and understand and also aesthetically pleasing. Since Jekyll leverages commonly used web technologies, we can easily push pixels by tweaking the CSS or quickly bring in a third party library with bower.io. It is a mature solution with extensive tutorials and articles (now one more), most problems we will face are already solved and documented.
Docs We Love
Documentation often offers you your first impression of a project. The following served as inspiration for our docs:
- Firebase Docs
- Great read on the design https://www.firebase.com/blog/2014-07-29-new-docs.html
Technology We Use
jekyll Static Site Generator
redcarpet Markdown Parser
anchor.js Great library to create anchor links
typed.js Provides the fancy typing at the top
animate.css Animation Framework
Bootstrap UI Framework
Font Awesome Icons
bower.io Package Manager
AWS S3 Site Hosting
Github Source Hosting