4 min readUpdated Oct 27, 2022

Hack GitHub to build your own wiki in five steps

Hack GitHub to build your own wiki in five steps
Thomas CampThomas Camp

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.

We considered at first making use of an existing git-based wiki such as Gollum, but soon realised that it wouldn’t work for us due to its need to run on a server with the Git repository. In addition, systems such as Heroku do not support it, making it a poor match for our needs.

Given this, we wanted to convert the GitHub Wiki to one of our own hosted sites. In order to accomplish this, we needed a number of things:

  • A web application framework
  • A method of presenting our markdown files in a static site
  • An authentication scheme to keep our wiki private
  • A place to host this new wiki
Our template for our wiki home 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.

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.

The search box in action

4. Authentication — Auth0

As we intended to use this wiki for internal use only, we needed some method of authentication when accessing it. Auth0 provides 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.

Conclusion

By making use of the above tools, it ended up being simple to create our own site to host our old GitHub Wiki. If you want to make your own wiki, check out our template code and try making something cool. Give us a shout on Twitter to show off what you built using this template!


Tom is a Tech Author and Dev at Ably

Join the Ably newsletter today

1000s of industry pioneers trust Ably for monthly insights on the realtime data economy.
Enter your email