and HTML and Markdown and README and Website and Demo

We all love READMEs. Well-written README shows you

• Library use-cases
• API and examples
• Architectural choices
• Build status and other shiny things
• Ideological outlook of the author (it better not be fashware)

README is the central part of software project presentation. There might be websites and manuals for some. But for most, README is The Home.

So I wondered, can one use HTML for README and have some fun logic there? It turns out, one can do that! Thanks to matrss comment in Forgejo issues, I now know that one can symlink READMEs to get a chimera that’s both a website and a README. You’re looking at one right now!

This is not only a website and README, it’s also a demo. This paragraph you’re (probably painfully) reading right now is being slowly rearranged. By JS script embedded in the README. This script is simply ignored / sanitized away by Codeberg (or any Git forge really) and thus not visible in README. But it works in the website view, and that enables the website to diverge from README significantly! So, if you want to have a fancy dynamic website but don’t really want to mess with a separate project. README website can help you!

Now let’s actually talk about how it work. Because I’m sure the implementation will make some of you weep and some of you shut your laptop lid in disgust.

It’s… README.html. Yes, I’m writing my READMEs in HTML. More reliable and portable this way. Well, you’re looking at a byproduct of this portability right now.

So the full workflow is:

• Create a README.html and fill it with HTML for the content you want to see. Github GFM spec can be a good reference for which tags you can use.
• Add some <script> and <style> to your heart content. Will be stripped away in Markdown view.
• Create a symlink Markdown file: ln -sf README.html README.md.
  • Given that Markdown has inline HTML feature, this HTML file is safely interpreted as valid Markdown.
  • This will be useful for display in the repository for those that want to read it as README.
  • Yes, Git can manage symlinks!
• Create a symlink index file: ln -sf README.html index.html.
  • This is what the website will display. But it’s still the README, just simlinked!
• Commit all of these
• Push to pages branch of the Codeberg repository (you use Codeberg and Codeberg Pages, right?)
• Codeberg will happily host the index.html under https://username.codeberg.page/repo/
• Link a custom domain to it, if you wish.
• Et voilà! You now have both a README and a website!
• But… at what cost?