Skip to content

GitHub Markdown

So...

My GitHub profile README is an incomprehensible mess.

There's just a whole load of duplicated image tags, <div align="center">s, monospace fonts which don't play well with screen readers, duplicated code for every single badge, outdated/stale project references which have hardcoded links, nested <picture> hell for dark-mode support, devicons spam, and so much more.

I just sat there and wondered - what if it didn't have to be like this? What if there was a world where people happily used simple syntax for READMEs that could still pop out?

Well, if you don't know me by now, sitting there and wondering is usually not the end of the story.

So... I went ahead and implemented it. I call it: gh-md. I know, iconic.

The project is also on GitHub.

It's also on the Actions Marketplace!

Anyway, let's go through it's capabilities.

Of course, you should start by adding this to your repository's .github/workflows/gh-md.yml:

name: Compile README
on:
  push:
    branches:
      - main
    paths:
      - 'README.gh.md'
  workflow_dispatch:
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: uukelele/gh-md@main

Firstly, you'll have to rename your README.md in your profile to README.gh.md, so that it's picked up by the action.

Or, you could create a new README.gh.md and ignore your old one. Depending on your choice, it might be preferred as it gives you a fresh start.

Now, let's show you some examples of what you can do with .gh.md files.

First of all, you can (of course) center text, images, badges, or whatever else:

<center>
    <h1>Hi!</h1>
</center>

Next, you can render badges. Like this:

<badge ltext="build" rtext="passing" color="green" />

Or more advanced:

<badge ltext="github action" rtext="compiles markdown" style="for-the-badge" logo="githubactions" logoColor="white" labelColor="black" color="rebeccapurple" href="https://github.com/uukelele/gh-md"/>

There are also many cool fonts.

The fonts are sourced from my alphabet.json GitHub gist - do check it out if you haven't already!

Because of this, there are a lot of different fonts to choose from. E.g.:

## <font="mono">STUFF</font>

<font="double">Many custom fonts are supported!</font>
<font="Funky">They also work well with screen-readers.</font>

...compiles to...

## <span aria-label="STUFF"><span aria-hidden="true">πš‚πšƒπš„π™΅π™΅</span></span>

<span aria-label="Many custom fonts are supported!"><span aria-hidden="true">π•„π•’π•Ÿπ•ͺ 𝕔𝕦𝕀π•₯π• π•ž π•—π• π•Ÿπ•₯𝕀 𝕒𝕣𝕖 𝕀𝕦𝕑𝕑𝕠𝕣π•₯𝕖𝕕!</span></span>
<span aria-label="They also work well with screen-readers."><span aria-hidden="true">Ρ‚Π½Ρ”Ρƒ Ξ±β„“Ρ•Οƒ ωσяк Ο‰Ρ”β„“β„“ ωιтн ѕ’яєєη-ΡΡ”Ξ±βˆ‚Ρ”ΡΡ•.</span></span>

Notice the <span> elements - they allow screen-readers to read the original content to the user while the fancy text is hidden, providing an accessible user experience.

You can also show off your projects!

<projects user="vercel" limit="3" sort="stars">
  <template>
    {{ project.name }} - ⭐ {{ project.stargazers_count }}
  </template>
</projects>

The user is your username. The limit is the maximum number of projects to show, and sort is how to sort the projects to determine which ones to show.

The underlying <template> supports Jinja2 syntax. You can also nest things, for example put a <badge> in there. For example:

<projects user="uukelele" limit="4" sort="stars">
  <template>
    <h3 align="left">
      {{ project.name }} 
      <a href="{{ project.html_url }}"><kbd>GitHub</kbd></a>
    </h3>
    <p align="left">
      {{ project.description }}
      <badge ltext="stars" rtext="{{ project.stargazers_count }}" logo="githubsponsors" style="social" />
      <badge ltext="forks" rtext="{{ project.forks_count }}" logo="forgejo" style="social" />
    </p>
  </template>
</projects>

These are badges inside the template. It compiles to:

<h3 align="left">
  web2app 
  <a href="https://github.com/uukelele/web2app"><kbd>GitHub</kbd></a>
</h3>
<p align="left">
  PyPI package for converting a website into an app.
  <img alt="Static Badge" src="https://img.shields.io/badge/stars-5-_?style=social&logo=githubsponsors&logoColor=white&labelColor=black&color=rebeccapurple" />
  <img alt="Static Badge" src="https://img.shields.io/badge/forks-3-_?style=social&logo=forgejo&logoColor=white&labelColor=black&color=rebeccapurple" />
</p>
<h3 align="left">
  hybridoma 
  <a href="https://github.com/uukelele/hybridoma"><kbd>GitHub</kbd></a>
</h3>
<p align="left">
  Hybridoma: Write Python, get a reactive frontend - no JS framework required
  <img alt="Static Badge" src="https://img.shields.io/badge/stars-4-_?style=social&logo=githubsponsors&logoColor=white&labelColor=black&color=rebeccapurple" />
  <img alt="Static Badge" src="https://img.shields.io/badge/forks-0-_?style=social&logo=forgejo&logoColor=white&labelColor=black&color=rebeccapurple" />
</p>
<!-- ...I'm sure you get it. -->

You can also render GitHub README stats, which I've noticed basically everyone has.

<stats user="yourusername" show-icons count-private theme="transparent" hide-border />

This is a simple one. You could also do things like add a most used languages next to it:

<center>
    <stats user="uukelele" base-url="https://github-readme-stats-clone-wine.vercel.app" show-icons count-private hide-border />
    <stats user="uukelele" base-url="https://github-readme-stats-clone-wine.vercel.app" route="/api/top-langs" layout="compact" hide-border />
</center>

By default, these output HTML supporting both light and dark theme:

<div align="center">
<picture>
    <source media="(prefers-color-scheme: dark)"  srcset="https://github-readme-stats-clone-wine.vercel.app/api?username=uukelele&show_icons=true&count_private=true&hide_border=true&theme=transparent"  />
    <source media="(prefers-color-scheme: light)" srcset="https://github-readme-stats-clone-wine.vercel.app/api?username=uukelele&show_icons=true&count_private=true&hide_border=true&theme=default" />
    <img alt="GitHub Stats" src="https://github-readme-stats-clone-wine.vercel.app/api?username=uukelele&show_icons=true&count_private=true&hide_border=true&theme=default" />
</picture>


<picture>
    <source media="(prefers-color-scheme: dark)"  srcset="https://github-readme-stats-clone-wine.vercel.app/api/top-langs?username=uukelele&hide_border=true&layout=compact&theme=transparent"  />
    <source media="(prefers-color-scheme: light)" srcset="https://github-readme-stats-clone-wine.vercel.app/api/top-langs?username=uukelele&hide_border=true&layout=compact&theme=default" />
    <img alt="GitHub Stats" src="https://github-readme-stats-clone-wine.vercel.app/api/top-langs?username=uukelele&hide_border=true&layout=compact&theme=default" />
</picture>
</div>

Last but not least, devicons! A lot of devs end up having these in their READMEs, for example to illustrate the stacks they are proficient in. So this comes built-in too:

<devicon name="python" height="32" />
<devicon name="react" type="original" height="32" />

These simply transpile to:

<img src="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/python/python-original.svg" height="32" alt="Icon for python" />
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons/react/react-original.svg" height="32" alt="Icon for react" />

That's about it for now.

Maybe in future, I could add a plugin system of sorts? I don't know. Drop your thoughts in the comments!

Anyway, here's an example of my README using the new .gh.md syntax:

(you can use this for inspiration, of course)

<center>
  <img src="https://github.com/uukelele/uukelele/blob/main/uukelele-2x.webp?raw=true" height="128" />
  <h1 align="center">uukelele</h1>
  <center>
    <badge ltext="semi professional" rtext="software engineer" logo="litiengine" color="rebeccapurple" style="for-the-badge" logoColor="white" labelColor="black" />
    <badge ltext="open source" rtext="contributor" logo="openmined" color="rebeccapurple" style="for-the-badge" logoColor="white" labelColor="black" />
    <badge ltext="bug bounty" rtext="hunter" logo="privateinternetaccess" color="rebeccapurple" style="for-the-badge" logoColor="white" labelColor="black" />
  </center>
</center>

<hr>

## <font="mono">ACHIEVEMENTS</font>

<badge ltext="security advisory" rtext="open web ui" logo="openbugbounty" color="rebeccapurple" href="https://github.com/open-webui/open-webui/security/advisories/GHSA-4j2m-5xvg-w788" />
<badge ltext="100+" rtext="stars" logo="githubsponsors" color="rebeccapurple" href="https://github.com/mindcraft-ce/mindcraft-ce" />

<img src="https://landsat.c00l.site/svg?text=uukelele&embed_image=true&attribution=true" />

# <font="mono">PROJECTS</font>

<projects user="uukelele" limit="4" sort="stars">
  <template>
    <h3 align="left">
      {{ project.name }} 
      <a href="{{ project.html_url }}"><kbd>GitHub</kbd></a>
    </h3>
    <p align="left">
      {{ project.description }}
      <badge ltext="stars" rtext="{{ project.stargazers_count }}" logo="githubsponsors" style="social" />
      <badge ltext="forks" rtext="{{ project.forks_count }}" logo="forgejo" style="social" />
    </p>
  </template>
</projects>

# <font="mono">STATS</font>
<center>
  <stats user="uukelele" base-url="https://github-readme-stats-clone-wine.vercel.app" show-icons count-private hide-border />
  <stats user="uukelele" base-url="https://github-readme-stats-clone-wine.vercel.app" route="/api/top-langs" layout="compact" hide-border />
</center>

<center>
  <devicon name="fastapi" height="40" />
  <img width="12" />
  <img src="https://raw.githubusercontent.com/astral-sh/uv/refs/heads/main/docs/assets/logo-letter.svg" height="40" alt="uv" />
  <img width="12" />
  <devicon name="svelte" height="40" />
  <img width="12" />
  <img src="https://raw.githubusercontent.com/ephaptic/ephaptic/refs/heads/main/docs/assets/logo.png" height="40" alt="ephaptic" />
</center>

<hr>

<p align="center">
  <i>❝ <font="serif_it">don't comment bad code β€” rewrite it.</font> ❞ – α—·α–‡Iα—©α‘Ž KEα–‡α‘ŽIGα•Όα—©α‘Ž</i>
</p>

And here's the compiled output, for those curious.

Comments