A Sneaky (Anti-)Pattern Hides Your Whole Codebase Under One Top-Level Directory

If you put a lot of care and effort into the appearance of your README, you might find it a little frustrating that when people visit, the first thing they see is a wall of dot-files and .yaml and .mylinterconfig.yaml.rc.json, and so on.

For example, let's take a look at the README for vhs by the impeccable team at charmbracelet:

What about a beautiful library - wouldn't it be nice to get rid of all that clutter on the README UI? Of course, the source code is important, but GitHub's repo landing page is a UI as well.

As it turns out, there's a clever trick you can do which is really unprofessional and inaccessible and confusing to any potential users or contributors... but it gets rid of all that clutter!

The .github directory

See, GitHub has a funny quirk where there are three (or four) canonical paths where you can place your community health files - CONTRIBUTING.md, CODE_OF_CONDUCT.md, etc. and they'll still show up on the repo's landing page:

(i) At the root

(ii) Under docs/

(iii) Under .github/

(iv) For a user-global version, you can also use your personal .github repository

You can even do this with your README. If you put your README at docs/README.md, it will (probably) show up on your repo's front page. If you have another version of the README at the root, however, that one will take precedence. And, if you put even another version at .github/README.md, that will in fact trump them all in the GitHub UI.

There's Only One Folder You Can't Live Without

If you have any GitHub Actions workflows in your repo, then you can't get rid of .github/ - you're stuck with it. But you can hide everything else underneath it. The README will still show up when users visit your repo; the README will still have those little tabs for your Code of Conduct, and Contributing, and Security docs. And everything else is tucked away chaotically in a single folder at the top level, and you can finally be happy.

[CAVEAT: There's one unfortunate catch, which is that if you move your LICENSE file, it won't be registered by GitHub's auto-discovery SPDX identifier.]

If you want to see an example of what I'm describing, I built a little demo repository with a functional node.js "Hello World" app, loads of config files, the whole works.

BEFORE:

AFTER:

To be clear: This is a really bad idea for the majority of use cases. But (a) it's fun; (b) it is somewhat useful. Even if you don't shove your whole application under .github, you might think about ways to reduce the scroll distance between the top of the README and your project's banner or badges, or whatnot. For example, if you have some image assets, throwing them into a folder at .github/assets might save you a row in the repo landing page UI. In my opinion, your README is your website, so show it some love and make these little optimizations.