Andrew Jorgensen
It's better than bad, it's good!

Naming Multi-file GitHub Gists

GitHub Gists use the first filename in ASCII sort order as the Gist's display name. If you have a multi-file Gist with documentation and code, the documentation probably gets used as the title because the convention is to capitalize it: README.md. In ASCII, uppercase letters come before lowercase, so README.md sorts before almost any code filename.

The usual advice is to prefix filenames with numbers or symbols to control sort order. That works, but it looks terrible.

There's a better way. GitHub displays readme files at the top of a Gist regardless of sort order, but still uses the first filename in ASCII order as the Gist's name. If your code filename sorts before readme.md, the Gist gets named after your code while the readme still appears first on the page.

You can see an example of this in a Gist I put together for building the macOS FIDO2 SSH provider from source, where the title is build-sk-libfido2.sh and the readme.md is displayed above it.