⚡ TL;DR

I’m happy to introduce RISS (README In Static Site), a tool that transforms a README like this one and insert it on your website, like so.

A README is a Project’s Cover

Your GitHub README is what your visitors on GitHub will encounter first. Thus, it needs to efficiently describe your project. There are a lot of advice online on how to craft a great README.

So you then go on and create a great README. Wonderful! 🎉

But I want the README on my Website

But then, you want to include your README on your static website, for instance in a portfolio or just to have a GitHub-independent homepage. You also want more control on the layout and theme than GitHub has to offer, and perhaps even privacy-preserving analytics. This is a common question and there are options based on ajax or on one GitHub Pages website per repository.

However, dynamically loading the README on the client side sounds like taking a performance hit for what is actually static content. Furthermore, maintaining one full-blown GitHub Pages static website for each small project, might not be worth it.

What if you could just change your README a bit so that it is ready for inclusion in your Eleventy or Hugo personal website, just like any other markdown page?

Enter RISS!

I wrote RISS (README In Static Site) for this very purpose.

With RISS, your project’s README is the source of truth. You just add simple comments for the small bits that need to differ between GitHub and your website. You then give the GitHub README to RISS as an input and the output is a file suitable for inclusion in your static site sources. As your README change and evolves, updating it is easy, you just rerun the script.

Let’s go over some examples!

Post Metadata

Hugo (and other static-site generators) need some metadata at the start of your post, like so:

---
title: "README In Static Site (RISS)"
date: 2021-08-21T08:15:54
description: "💎 Transform and insert your GitHub README in your static site"
---

Of course, we don’t want to have this on GitHub. We thus put it in a comment, so that it remains hidden on GitHub:

<!-- insert
---
title: "README In Static Site (RISS)"
date: 2021-08-21T08:15:54
description: "💎 Transform and insert your GitHub readme in your static site"
---
end_insert -->

given the above comment as input, RISS outputs:

---
title: "README In Static Site (RISS)"
date: 2021-08-21T08:15:54
description: "💎 Transform and insert your GitHub README in your static site"
---

and the resulting file is usable by Hugo!

More

GitHub prohibits embedding arbitrary scripts for security reason. But what if you want to embed an asciinema player on your project homepage, so that users can play the asciicast as they would a standard video? You can have a placeholder with the link on GitHub as asciinema documentation advises and then use RISS to replace it with the full player on your website. You will find how to do that in the documentation. Plus, here is an example README this one doing this (and the corresponding website, look for the asciicast that autoplays).

See also how to automate the update of all these READMEs with, for instance, GitHub Action.

Thank you for reading!