Kudos for making it reusable and not specific to a single static site generator. I would have just used a Zola shortcode and never even thought anybody else might want it (as I did for a git log renderer used here).
I did something similar last year: https://idiomdrottning.org/README-to-blog using a file-include plugin to just include the README file directly as opposed to using actions to sync them up.
(We think alike in more ways than one since I also has a project named RISS, although mine is a tabletop RPG related thing.)
Cool!
I also run the readme-update make target locally sometimes when I made the changes to the README files and want a local preview before pushing to the live website. The way I use GitHub actions is more as a fallback, to avoid having the website and the README from the repo desynchronized for too long in case I don’t rebuild my site manually for a while. It’s admittedly a slightly different use from what the RISS README suggests.
Been doing that too for my programs, using an homemade script. (See the README and website). I run it off my server’s git hooks.
The part I like the most about this “practice” (exposing the bare README as a website) is that it forces me to write “better” README, and actually take the time to sit down and put useful information inside it.
In essence, my script mostly does markdown README | cat header.html - > index.html everytime I git push to the repo. I then tailored this script to my specific needs to add some sugar to it (generate manpages and link to them, add a link to the LICENCE file, link the repo, tarball releases, …).
I’m not a fan of your solution however, as its very reason to exist is because of Github limitations (if I understand it correctly). It could also make the “plaintext” version of the README very messy or confusing to read, with the “github conditional blocks” being still displayed.
But that’s just me being grumpy, and it’s pretty cool that you decided to base your website of your project’s README, so keep going ! Many people host their repo on Github, and if that can make them write better README and start hosting their webpages by themselves, I’m more that happy to see it succeed and gain traction ;)
It could also make the “plaintext” version of the README very messy or confusing to read, with the “github conditional blocks” being still displayed.
That’s a fair point, especially with the front matter put at the beginning. A solution might be to have a template README.md.tpl with the annotations, that would pass through riss to create the webpage and a second awk script, very similar to riss, could be used to remove these annotations from the README.md.tpl to create a README.md (all of this could be automated with hooks). What do you think?
Kudos for making it reusable and not specific to a single static site generator. I would have just used a Zola shortcode and never even thought anybody else might want it (as I did for a git log renderer used here).
Thanks! The git log render looks really nice, I think it’s great to feature that on your website.
I did something similar last year: https://idiomdrottning.org/README-to-blog using a file-include plugin to just include the README file directly as opposed to using actions to sync them up.
(We think alike in more ways than one since I also has a project named RISS, although mine is a tabletop RPG related thing.)
Cool!
I also run the
readme-updatemake target locally sometimes when I made the changes to the README files and want a local preview before pushing to the live website. The way I use GitHub actions is more as a fallback, to avoid having the website and the README from the repo desynchronized for too long in case I don’t rebuild my site manually for a while. It’s admittedly a slightly different use from what the RISS README suggests.Been doing that too for my programs, using an homemade script. (See the README and website). I run it off my server’s git hooks.
The part I like the most about this “practice” (exposing the bare README as a website) is that it forces me to write “better” README, and actually take the time to sit down and put useful information inside it.
In essence, my script mostly does
markdown README | cat header.html - > index.htmleverytime Igit pushto the repo. I then tailored this script to my specific needs to add some sugar to it (generate manpages and link to them, add a link to the LICENCE file, link the repo, tarball releases, …).I’m not a fan of your solution however, as its very reason to exist is because of Github limitations (if I understand it correctly). It could also make the “plaintext” version of the README very messy or confusing to read, with the “github conditional blocks” being still displayed.
But that’s just me being grumpy, and it’s pretty cool that you decided to base your website of your project’s README, so keep going ! Many people host their repo on Github, and if that can make them write better README and start hosting their webpages by themselves, I’m more that happy to see it succeed and gain traction ;)
That’s a fair point, especially with the front matter put at the beginning. A solution might be to have a template
README.md.tplwith the annotations, that would pass through riss to create the webpage and a second awk script, very similar to riss, could be used to remove these annotations from theREADME.md.tplto create aREADME.md(all of this could be automated with hooks). What do you think?