{"id":15919496,"url":"https://github.com/cljoly/readme-in-static-site","last_synced_at":"2025-05-07T01:41:51.952Z","repository":{"id":80531105,"uuid":"398378798","full_name":"cljoly/readme-in-static-site","owner":"cljoly","description":"💎 Transform and insert your GitHub readme in your static site.","archived":false,"fork":false,"pushed_at":"2025-03-09T21:23:35.000Z","size":91,"stargazers_count":37,"open_issues_count":3,"forks_count":5,"subscribers_count":1,"default_branch":"moved","last_synced_at":"2025-03-31T05:03:04.821Z","etag":null,"topics":["hacktoberfest","hugo","static-site","static-site-generator","zola"],"latest_commit_sha":null,"homepage":"https://cj.rs/readme-in-static-site/","language":"Awk","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cljoly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://cj.rs/donate/"]}},"created_at":"2021-08-20T19:18:01.000Z","updated_at":"2025-03-09T21:14:25.000Z","dependencies_parsed_at":"2024-10-29T01:15:19.549Z","dependency_job_id":null,"html_url":"https://github.com/cljoly/readme-in-static-site","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cljoly%2Freadme-in-static-site","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cljoly%2Freadme-in-static-site/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cljoly%2Freadme-in-static-site/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cljoly%2Freadme-in-static-site/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cljoly","download_url":"https://codeload.github.com/cljoly/readme-in-static-site/tar.gz/refs/heads/moved","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252798153,"owners_count":21805837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","hugo","static-site","static-site-generator","zola"],"created_at":"2024-10-06T19:01:44.642Z","updated_at":"2025-05-07T01:41:51.927Z","avatar_url":"https://github.com/cljoly.png","language":"Awk","funding_links":["https://cj.rs/donate/"],"categories":["Awk"],"sub_categories":[],"readme":"\u003c!-- insert\n---\ntitle: \"README In Static Site (RISS)\"\ndate: 2021-08-21T08:15:54\ndescription: \"💎 Transform and insert your GitHub readme in your static site\"\ntags:\n- Open Source\n- Tools\n- Static Site\n- Hugo\n- HackerNewsHomepage\nrepo_url: \"https://codeberg.org/cljoly/readme-in-static-site\"\n---\n{{\u003c github_badge \u003e}}\n{{\u003c rawhtml \u003e}}\n\u003cdiv class=\"badges\"\u003e\n{{\u003c /rawhtml \u003e}}\nend_insert --\u003e\n\u003c!-- Powered by https://cj.rs/riss --\u003e\n\n\u003c!-- remove --\u003e\n# 💎 README In Static Site (RISS)\n\u003c!-- end_remove --\u003e\n\n[![Get it on codeberg](https://raw.githubusercontent.com/cljoly/readme-in-static-site/refs/heads/moved/get-it-on-codeberg.svg)](https://codeberg.org/cljoly/readme-in-static-site)\n\n[![GitHub code size in bytes](https://img.shields.io/github/size/cljoly/readme-in-static-site/riss.awk?color=purple)](https://github.com/cljoly/readme-in-static-site/blob/main/riss.awk) ![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/cljoly/readme-in-static-site?color=darkgreen\u0026sort=semver) [![CI](https://codeberg.org/cljoly/readme-in-static-site/actions/workflows/checks.yml/badge.svg)](https://github.com/cljoly/readme-in-static-site/actions/workflows/checks.yml) [![](https://img.shields.io/badge/powered%20by-riss-lightgrey)](https://cj.rs/riss)\n\n\u003c!-- remove --\u003e\n![RISS in action](https://user-images.githubusercontent.com/7347374/134990638-d1ebb3ba-89db-4bbf-b00f-dc150e3b35fc.png)\n\u003c!-- end_remove --\u003e\n\u003c!-- insert\n![RISS in action](/blog/putting-readmes-on-your-static-site/riss-in-action.png)\nend_insert --\u003e\n\n\u003c!-- insert\n{{\u003c rawhtml \u003e}}\n\u003c/div\u003e\n{{\u003c /rawhtml \u003e}}\nend_insert --\u003e\n\nThis [fast][] [script][] allows you to insert your GitHub README in your static site and apply transformations. For instance, you can read this [README on GitHub](https://github.com/cljoly/readme-in-static-site/blob/main/README.md) and [on my website](https://cj.rs/readme-in-static-site).\n\n### Why?\n\nThe GitHub README of your repo needs to efficiently describe your project to GitHub’s visitor. But featuring your project on your website allows you to (among other things):\n* have more control on the theme and layout,\n* insert scripts that GitHub would prohibit (like [asciinema](#replace-asciinema-image)),\n* have your project’s homepage independent of your hosting platform, if you wish to change at some point.\n\nChances are that for small projects, the page about your project is very similar to the GitHub README. Don’t duplicate efforts, describe the differences! This [has](https://github.com/vhodges/stitcherd) [been](https://dev.to/lornasw93/github-readme-on-portfolio-project-page-51i8) a [long-awaited](https://richjenks.com/github-pages-from-readme/) [feature](https://medium.com/@bolajiayodeji/how-to-convert-github-markdown-files-to-a-simple-website-b08602d05e1c), in [one](https://news.ycombinator.com/item?id=29305990) [form](https://stackoverflow.com/q/48919200/4253785) or [another](https://stackoverflow.com/a/69296054/4253785).\n\nSee this [blog post](https://cj.rs/blog/putting-readmes-on-your-static-site/) for more details.\n\n## Testimonials\n\n[![](https://img.shields.io/badge/dynamic/json?color=Orange\u0026label=HackerNews\u0026query=%24.score\u0026url=https%3A%2F%2Fhacker-news.firebaseio.com%2Fv0%2Fitem%2F29304376.json\u0026logo=ycombinator\u0026color=orange)](https://news.ycombinator.com/item?id=29304376) [![](https://img.shields.io/badge/dynamic/json?color=green\u0026label=Lobsters\u0026query=%24.score\u0026url=https%3A%2F%2Flobste.rs%2Fs%2Fa4jzvv%2Freadme_static_site_riss.json\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAAXNSR0IArs4c6QAAAAZiS0dEAL0ALQAtZF7+HAAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB9wCCBAuLt2rqugAAACMSURBVDjL1ZMxCsJQEERfRPEk9im9mGfxBpaCnaXmBraeQEidKsKz2eIb/peEIOLAwu4Ws7PMbsUAKlOwYCaWmd4aWCV1B4yXpR59R61SitwKDdBHfgPaSTsF8zOmHz5NLykAeCRqvuvCfxGcgP0YF3ZqHy7c1Yt6jfo8dCF3idvkQjcRRVQ/f6bZBC+RBoeZnlCyqwAAAABJRU5ErkJggg==\u0026labelColor=500000)](https://lobste.rs/s/a4jzvv/readme_static_site_riss#c_hiil4z.json)\n\nRISS made it to the first page of [HackerNews](https://news.ycombinator.com/item?id=29304376) and [Lobsters](https://lobste.rs/s/a4jzvv/readme_static_site_riss) and got comments like:\n\n\u003e I never really understood the idea to have a separate README and index page. Glad to see i'm not the only one :)\n\n[southerntofu](https://news.ycombinator.com/item?id=29305519)\n\n\u003e Kudos for making it reusable and not specific to a single static site generator. […]\n\n[hannu](https://lobste.rs/s/a4jzvv/readme_static_site_riss#c_hiil4z)\n\n\u003e […] A small but good idea, I like how simple riss.awk is.\n\n[lifthrasiir](https://news.ycombinator.com/item?id=29305070)\n\n### Run It (Nothing to Install)\n\nTo try it with [Hugo][hugo] or [Zola][zola], run the following in your static-site sources:\n```sh\nwget https://cj.rs/riss.awk\nawk -f riss.awk /path/to/my-project/README.md \u003e content/my-project.md\n```\n\nIf you don’t use Hugo or Zola, no problem! It should also work with any markdown-based static-site generator. Just put the markdown file where it makes sense for that generator.\n\nTo automatically update these files in your static-site sources, see [Automate with GitHub Actions](#automate-with-github-actions) below. Since RISS is based on Awk, there is nothing to install, besides copying the script itself!\n\n## Example\n\n### Add a Front Matter\n\nMost static site generators require a “[front matter](https://gohugo.io/getting-started/configuration/#configure-front-matter)” at the beginning of a markdown file to attach some metadata. But you don’t want to add this to your GitHub README! Let’s hide this on GitHub and have it in the script’s output.\n\nIn you .md file on GitHub, put:\n\n    \u003c!-- insert\n    ---\n    title: \"README In Static Site (RISS)\"\n    date: 2021-08-21T10:15:54\n    ---\n    end_insert --\u003e\n    \u003c!-- Powered by https://cj.rs/riss --\u003e\n    \u003c!-- remove --\u003e\n    \n    # README In Static Site (RISS)\n    \u003c!-- end_remove --\u003e\n\nThe output of the script will be:\n\n    ---\n    title: \"README In Static Site (RISS)\"\n    date: 2021-08-21T10:15:54\n    ---\n    \u003c!-- Powered by https://cj.rs/riss --\u003e\n\nand this piece of yaml will be hidden on GitHub!\n\n### Replace Asciinema Image\n\nYou can’t embed the asciinema player on GitHub for security reasons. So the [asciinema documentation](https://asciinema.org/docs/embedding) suggests using an image there and to link it to a webpage with the player. But on your own website, you can embed this player.\n\nIn your .md file, put:\n\n    \u003c!-- remove --\u003e\n    [![Finding the repositories with “telescope” in their name, with the README in the panel on the right](https://asciinema.org/a/427156.svg)](https://asciinema.org/a/427156)\n    \u003c!-- end_remove --\u003e\n    \u003c!-- insert\n    \u003casciinema-player src=\"./telescope.cast\" poster=\"npt:0:04\"\u003e\u003c/asciinema-player\u003e\n    end_insert --\u003e\n\nThe output will contain only the asciinema player:\n\n    \u003casciinema-player src=\"./telescope.cast\" poster=\"npt:0:04\"\u003e\u003c/asciinema-player\u003e\n\n*Note*: you also need to add the JS/CSS files of the asciinema player somewhere in your theme. This [Hugo module][hugo_ascii] makes it easy.\n\n### More\n\nSee the [input file (typically on GitHub)](https://github.com/cljoly/readme-in-static-site/blob/main/test.md) and the [output of the script](https://github.com/cljoly/readme-in-static-site/blob/main/test_output.md). You can find another real word [README](https://github.com/cljoly/telescope-repo.nvim/blob/master/README.md) converted to a [webpage](https://cj.rs/telescope-repo-nvim/) (this gives another example of asciinema conversion using a Hugo shortcode).\n\nWith some shell scripting, you could also transform all the markdown files in your repo and put them in a subdirectory of your site, so that your project’s documentation, policy, etc… lives on your site or even on a site of its own.\n\n### Your Example!\n\nHave you used this script to transform some markdown (or other) and insert it on your website? [Open an issue][issue] if you would like a link to your use case from this README!\n\n* **telescope-repo.nvim**: [readme](https://github.com/cljoly/telescope-repo.nvim/blob/master/README.md), [website](https://cj.rs/telescope-repo-nvim/); features an Asciinema clip.\n* **neovide**: [readme](https://github.com/neovide/neovide/blob/main/README.md), [first iteration of their website](https://neovide.dev/), [PR setting this up](https://github.com/neovide/neovide/pull/1114). They have now moved to mdbook and that’s great! RISS makes the first iteration of your website easy and you are free to move to more complete solutions when your project grows.\n* **Hugo APT Repository**: [readme](https://github.com/8hobbies/hugo-apt/blob/master/README.md), [website](https://hugo-apt.8hob.io/), [PR setting it up](https://github.com/8hobbies/hugo-apt/pull/12).\n\n## Transformations Reference\n\nThe transformations are driven by HTML comments, so that you can have different results when comments are ignored (e.g. in your GitHub README) and after executing the script on your markdown file.\n\n### Escaping\n\n**It is important that your comment starts at the beginning of the line:** spaces are used for escaping, meaning that if the comment has spaces at the beginning of the line, it is ignored.\n\nSo this is escaped\n```\n    \u003c!-- insert\n```\nbut this is not\n\n    \u003c!-- insert\n\n### Insertion\n\nUse these two lines for text you want to have in your output, but not in the raw .md file.\n\n    \u003c!-- insert\n    end_insert --\u003e\n\n### Remove\n\nUse these two comments for text you want to have in your raw .md file, but not in the output\n\n    \u003c!-- remove --\u003e\n    \u003c!-- end_remove --\u003e\n\n## Spread the Word\n\nIf you find this script useful, please consider inserting the following in your readme:\n```html\n\u003c!-- Powered by https://cj.rs/riss --\u003e\n```\nThis will help other people find the script. *Thanks for spreading the word!*\n\nIf you feel especially charitable, you could put this badge somewhere:\n\n[![](https://img.shields.io/badge/powered%20by-riss-lightgrey)](https://cj.rs/riss)\n\nwith for instance this code:\n```markdown\n[![](https://img.shields.io/badge/powered%20by-riss-lightgrey)](https://cj.rs/riss)\n```\n\n## Breaking API Changes\n\nWe follow [semver][] and any change that change would cause real world READMEs to be converted differently requires a new major version. In particular, the following is a breaking change:\n* adding new keywords (like `remove` or `insert`), as they may be used in the README prior to their introduction in RISS,\n* changing a keywords syntax.\n\n## Benchmark\n\n**Processes 17600 lines in 10 ms**\n\n```bash\n$ for i in {1..100}; do shuf README.md \u003e\u003ebench.md; done # Create a big md file\n$ wc -l README.md\n176 README.md\n$ wc -l bench.md\n17600 bench.md\n$ hyperfine 'awk -f riss.awk README.md' 'awk -f riss.awk bench.md'\n```\n\n| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |\n|:---|---:|---:|---:|---:|\n| `awk -f riss.awk README.md` | 2.8 ± 0.2 | 2.4 | 3.7 | 1.00 |\n| `awk -f riss.awk bench.md` | 9.7 ± 0.4 | 8.9 | 10.7 | 3.46 ± 0.30 |\n\n## Automate with GitHub Actions\n\nYou can automatically update the markdown file in the sources of your site with GitHub Actions. Add this workflow to, for instance, `.github/workflows/readme.yml`:\n\n```yaml\nname: Update README files\n\non:\n  schedule:\n    - cron: '30 */2 * * *'\n  push:\n    branches:\n    - master\n  # To run this workflow manually from GitHub GUI\n  workflow_dispatch:\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - name: Check out the repo\n      uses: actions/checkout@v2\n    - name: Get the latest READMEs\n      run: make readme-update\n    - name: Commit and push if there are changes\n      run: |-\n        git diff\n        git config --global user.email \"bot@example.com\"\n        git config --global user.name \"bot\"\n        git diff --quiet || (git add -u \u0026\u0026 git commit -m \"Update READMEs\")\n        git push\n```\n\nand then your `Makefile` may contain something like:\n\n```make\nreadme-update:\n\tcurl https://raw.githubusercontent.com/cljoly/readme-in-static-site/main/README.md | awk -f riss.awk \u003econtent/readme-in-static-site.md\n```\n\nAlternatively, you might configure your repositories to trigger a website rebuild when committing on your README, for instance using [GitHub actions webhooks][gh_webhook].\n\n## Contributions are Welcome!\n\nFeel free to [open an issue][issue] to discuss something or to send a PR.\n\nSee also the [Spread the Word][stw] section if you would like to make more folks aware of this script.\n\n![GitHub](https://img.shields.io/github/license/cljoly/readme-in-static-site)\n\n[hugo]: https://gohugo.io/\n[zola]: https://www.getzola.org/\n[hugo_ascii]: https://cj.rs/gohugo-asciinema/\n[issue]: https://github.com/cljoly/readme-in-static-site/issues/new\n[fast]: #benchmark\n[stw]: #spread-the-word\n[script]: https://cj.rs/riss.awk\n[gh_webhook]: https://mainawycliffe.dev/blog/github-actions-trigger-via-webhooks/\n[semver]: https://semver.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcljoly%2Freadme-in-static-site","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcljoly%2Freadme-in-static-site","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcljoly%2Freadme-in-static-site/lists"}