You’re proud of your GitHub repository, and you want to serve its README.md as an HTML page. The default templates GitHub Pages offers don’t satisfy you. However, you can do this yourself, as it only takes a Markdown file and a gh-pages branch.

Here’s a quick way to set this up and automate it. I’m assuming you have a repository at GitHub with a master branch containing README.md.

Step 1: Install Release It! (at least v2.3.0):

npm install release-it -g

Step 2: Create and check out the gh-pages branch in your project.

Step 3: Create a file named front.yml:

---

title: awesomesauce

layout: default

---

Step 4: Create a folder named _layouts and add this default.html template:

<!doctype html>

<html lang="en">

<head>

<meta charset="UTF-8">

<title>{{ page.title }}</title>

</head>

<body>

{{ content }}

</body>

</html>

Make sure to leave the {{ content }} somewhere for the content to be inserted by Jekyll. You can add any CSS and JS you want, just put them in the gh-pages branch and hook them up with <link> and <script> elements in the template.

Step 5: Add and commit the files and push it to the remote repository.

Step 6: Switch to the master branch, and create a file .release.json containing this (replace “user” and “repo” with your own):

{

"dist": {

"repo": "git@github.com:user/repo.git#gh-pages",

"beforeStageCommand": "cat front.yml ../README.md > index.md"

}

}

Done!

Now, each time you create a new release in your master branch, the Release It! configuration will automatically update the gh-pages branch for you. The front-matter and README.md are concatenated into index.md, which will be processed by GitHub Pages (Jekyll), and eventually wrapped in the default.html layout and served as index.html at http://user.github.io/repo.

Example

An example following the steps above can be seen at https://github.com/webpro/github-pages-example which is being served at http://webpro.github.io/github-pages-example.

Feedback

Got any questions or feedback? Feel free to contact me at Twitter (https://twitter.com/webprolific), or open an issue at https://github.com/webpro/release-it.

Further resources