Putting READMEs on your Static Site
Tags: github, markdown, showdev
Published: 2021-09-27 21:42:26

## TL;DR

I’m happy to introduce [RISS][RISS] (*README In Static Site*), a tool that transform a README like [this one][telescope-repo] and insert it on your website, [like so][telescope-repo-site].

[![RISS in action](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/trxb7683pnl7uxyegjbq.png)][RISS]

## 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](https://github.com/zenika-open-source/promote-open-source-project#readme) 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][matomo]-[preserving][plausible] [analytics][goat].
This is a [common][q1] [question][q2] and there are options based on [ajax] or on one [GitHub Pages][gh-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][11ty] or [Hugo] personal website, just like any other markdown page?    

## Enter [RISS][RISS]!

I wrote [RISS][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][frontmatter] 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][doc-script]. Plus, here is an example README [this one][telescope-repo] doing this (and the [corresponding website][telescope-repo-site], look for the asciicast that autoplays).


See also how to [automate][doc-auto] the update of all these READMEs with, for instance, GitHub Action.

Thank you for reading, don’t hesitate to ask any questions in the comments!

[portfolio]: https://dev.to/lornasw93/github-readme-on-portfolio-project-page-51i8
[ajax]: https://richjenks.com/github-pages-from-readme/
[gh-pages]: https://medium.com/@bolajiayodeji/how-to-convert-github-markdown-files-to-a-simple-website-b08602d05e1c
[q2]: https://stackoverflow.com/q/48919200/4253785
[q1]: https://stackoverflow.com/q/16226202/4253785
[RISS]: https://cj.rs/readme-in-static-site/?ref=devto20210926
[doc-script]: https://cj.rs/readme-in-static-site/?ref=devto20210926#replace-asciinema-image
[doc-auto]: https://cj.rs/readme-in-static-site/?ref=devto20210926#automate-with-github-actions
[Hugo]: https://gohugo.io/
[11ty]: https://www.11ty.dev/
[matomo]: https://matomo.org/
[plausible]: https://plausible.io/
[goat]: https://www.goatcounter.com/
[asciinema]: https://asciinema.org/
[telescope-repo]: https://github.com/cljoly/telescope-repo.nvim
[telescope-repo-site]: https://cj.rs/telescope-repo-nvim/?ref=devto20210926
[frontmatter]: https://gohugo.io/content-management/front-matter