Here at Ably, we have an immense amount of information that needs to be shared among our employees, from the various services we use to the usage of our own system and various company protocols.
Until recently, we’ve been using the GitHub Wiki functionality to do the job but lately, we have had a few issues with this. Firstly, there’s no form of version control for the wiki available through the GitHub interface. Secondly, we wanted the wiki’s content to be easily searchable from the actual page.
You can find the base code used to build this tool, in our GitHub Repository.
1. Web Application Framework — Sinatra
We based our wiki on Sinatra, a web application library written in Ruby. This is a really simple way to get the foundation of your site running. It comes with some great tutorials on how to get started. With Sinatra we had the infrastructure to present our pages, however we still needed a way to interpret our markdown files to display them.
2. Presenting Markdown files — Jekyll
To convert our markdown pages we settled on Jekyll. Jekyll will process any markdown, HTML, and CSS and combine it all into a static site, which is exactly what we needed. By creating some CSS files to structure our pages, and storing our markdown pages in a folder, we were able to construct HTML pages with ease. Once the static site has been generated into a folder called _site, we were able to have Sinatra use this folder as a basis for presenting pages.
3. Searching Pages — Simple-Jekyll-Search
Beyond simply hosting and presenting our wiki pages, we wanted to be able to search through them. To do this, we constructed a sidebar containing the titles of each of the searchable pages, and then made use of Simple-Jekyll-Search to easily search through these titles and content of each page. This was just a matter of defining the search structure and results we wanted in a search.json file, followed by presenting the results in place of the usual sidebar results.
4. Authentication — Auth0
As we intended to use this wiki for internal use only, we needed some method of authentication when accessing it. Auth0provides a simple API to authenticate throughout the site, abstracting away all the complexities involved with authentication.
5. Deploying — Heroku
Finally, we needed a way to make our site widely accessible. In order to simplify the process, we made use of Heroku for hosting our new site. With its easy GitHub integration, this allows us to not only automatically pull new wiki material from our master branch when it gets updated, but also allows access to versioned sites for testing.