referencing the latest tag and/or release version in the readme

[robaho]

Select Topic Area

Question

Body

I don't use github releases. I want to have my README.md rendered showing the latest tag in a branch as a variable replacement. I can do this by creating a template file, and a prehook to generate the README.md, and git add the file, etc.

There has to be an easier way...

Why can't we use something like {{ current_tag:branch_name }} so {{ current_tag: main }} to have it replaced by this when rendering.

Similarly for latest release, etc.

[Gor-Hoveyan]

Unfortunately, GitHub's Markdown rendering doesn't support dynamic variable substitution or templating in README files natively. The Markdown is rendered as static content.
Here are the main approaches people typically use:

The pre-commit hook approach you mentioned (reliable but requires setup)
GitHub Actions to auto-update the README when tags/releases change
Using badges instead, which are dynamic:
![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/username/repo)

The badge approach is probably the simplest solution - it's dynamic and requires no setup. You can customize the style and format.

[robaho]

Thanks for the badge link. I am surprised there isn't one that generates a pom file as a text SVG - at least I can't find it. The 'tag' badge you linked can't really be used because it puts a 'v' in front (which is very bad imo - as the tag doesn't have the v, but some projects already tag with a v).

The badges are kind of hokey though...

github already does custom html rendering for the readme files - this seems like a trivial addition that would make things so much simpler in just about every case.

[robaho]

The main issue with the 'pre-commit' templating solution is that you have a chicken and the egg. You need to commit the file, but the file is generated based on the tag, so you have to create the tag first - making it so that the README.md commit is AFTER the the tagged commit.