Markdown files as static content
Tags: ruby, rails, octokit, staticsite
Published: 2019-05-11 23:03:43

---
title: Markdown files as static content
published: true
tags: ruby,rails,octokit,static-site
canonical_url: https://medium.com/@nisevi/markdown-files-as-static-content-1ac98b401d68
---

How to use markdown files from a GitHub repository as static content in your website?

![](https://cdn-images-1.medium.com/max/1024/1*Trx5kyF44KU7WqS8kDRCTA.jpeg)

### Context

We will be talking about a feature implemented on [Agile Ventures](https://www.agileventures.org) that allow us to use markdown files as static content of the website. This idea was born when thinking about how to let developers contribute to the content of the site in an easier way while taking advantage of the GitHub ecosystem.

What we were using for editing the static content on the website was the [mercury](https://github.com/jejacks0n/mercury) editor. But the problem with that editor is that has fallen out of maintenance. I have done a couple [changes](https://github.com/AgileVentures/mercury/commits/master) to that gem in order to make it work with rails 5. We are now using a custom version in a [forked repository](https://github.com/AgileVentures/mercury), but that is another story ;).

As the main goal, we want to get rid of that editor from our system. So, we have started from removing the functionality that involves **static pages**, for, later on, remove it from the **projects** as well. All the code related to the changes I have done in order to implement this feature can be found [here](https://github.com/AgileVentures/WebsiteOne/pull/2252).

### Preparations

We need the repository from where we want to pull the content. Currently, our static pages live in this [repository](https://github.com/AgileVentures/AgileVentures) and we are pulling data from the root path, and working only with the markdown files.

The application is making requests to the [GitHub API](https://developer.github.com/v3/) by using the [octokit](https://github.com/octokit/octokit.rb) gem. So, we need to have the *octokit* gem in our Gemfile:

`gem 'octokit', '~\> 4.8'`

And the [kramdown](https://github.com/gettalong/kramdown) gem is being used for converting the markdown content into HTML. For adding the *kramdown* gem to the Gemfile:

`gem 'kramdown', '~\> 1.16', '\>= 1.16.2'`

### Creating the service

As we will be using the *kramdown* gem for converting the content in a markdown file into HTML, we need to isolate the gem behavior. For doing this, we are going to create a class that will serve as a wrapper for the *kramdown* functionality.

{% gist https://gist.github.com/nisevi/d2441c7589fc945660a1a9ef8f61aad6 %}

> The path to changeable and maintainable object-oriented software begins with classes that have a single responsibility. Classes that do one thing isolate that thing from the rest of your application. This isolation allows change without consequence and reuses without duplication.

> Sandi Metz.

### Crafting the rake task

Now we need to create the rake task that is gonna be scheduled by using the [Heroku Scheduler](https://devcenter.heroku.com/articles/scheduler) add-on. It will look something like this:

![](https://cdn-images-1.medium.com/max/750/1*gwhLTDPsj7vBpZP-i7A4JA.png)

I have created this rake task by following the code styles that the project is already implementing in order to preserve consistency within the system. So this rake task will call the logic that resides in the GithubStaticPages module.

{% gist https://gist.github.com/nisevi/113accbb7142157346ca27882a65cde0 %}

The following code is the logic that we are using for pulling the content from markdown files, convert it to HTML and save it using the StaticPages model. This means that all HTML code related to a particular static content lives in the database.

{% gist https://gist.github.com/nisevi/9f3c7838e5df1d609b77f79c87a6fa94 %}

### Rendering the content

Since we have to change the way we CRUD static pages on the system, and we now will be using the GitHub ecosystem for doing it, there is no change to be implemented in the way we get the content from the database. The only difference is that now we have been able to remove the actions that were tightly coupled to the mercury editor.

{% gist https://gist.github.com/nisevi/8126f1616b0b1a994673ab8357952691 %}

Finally, we just get the HTML from the body attribute in the page object.

{% gist https://gist.github.com/nisevi/28a0e097875a35b6d9c65fddc5f8e8cd %}

### What's next?

Instead of having this rake task running daily within our system, we could be using [GitHub Webhooks](https://developer.github.com/webhooks/) for achieving the same goal. But for doing this, we need first to create the functionality within our system that will handle those requests.

Talking about priorities, I will keep working on the removal of the mercury editor from the system since that is the general goal. Once removed, with the AV (Agile Ventures) team, we will decide what to do next. I'll keep you posted;)!

### Notes

Something that it worth to mention is that this feature only creates and updates the static pages on the database. It doesn't remove pages that no longer exist in the repository from where we pull the content. This was a decision that we discussed within the team to be implemented in this way.

All code shared here is Open Source and you will find it in the [WebsiteOne](https://github.com/AgileVentures/WebsiteOne) repository. If you want to contribute to the code, even if it is a small change where you are thinking "this could have been done in this other way". I invite you to create a pull request. It doesn't matter how small the change is, it will help us to improve and make our code better, while you will be contributing to an Open Source project ;).

* * *