Beautify your GitHub repo

I hope that by now, everybody is familiar with READMES. If one places a README file at the root of one’s repo, GitHub will display its content on the repo’s homepage.

However, here are a couple of tips you may not know.

The README may be in different formats:

Note that HTML doesn’t work: GitHub displays the raw HTML code, not the "rendered" HTML.

Additionally, one can set a README for an organization. You first need to create a repository named like the organization. Then, create the README file you want under the /.github/profile/ directory. For an example, check this blog’s organization that shows a custom page.

For more details, check the documentation.

If you want people to use your code, you should tell them under which terms they can use it. It’s precisely the goal of licensing your code. Traditionally, most packages have a LICENSE (or LICENSE.txt) file at their root. GitHub has adopted this practice.

You can choose any license you want, but the GitHub UI provides a good help for Open Source ones. Go to Add file  Create new file. If you name the new file LICENSE, a new button will pop up: Choose a license template. When you click on it, GitHub offers the following choice:

You can choose one to check its content. GitHub displays its permissions, limitations, and conditions:

You can now Review and submit. At this point, you are faced with three choices:

After adding the license, GitHub displays it on the right of the repository’s page.

For more details, check the documentation.

GitHub automatically adds the configured code owners to pull requests. You define them in a CODEOWNERS file, whose format is somewhat similar to .gitignore.

Here’s a quick sum-up of how GitHub handles it:

GitHub skips invalid configuration lines. To verify, you can use the UI:

Projects want people to report security issues. But the communication channel(s) needs to be private so that hackers don’t learn about the issue before it can be mitigated, fixed, or both. For this, GitHub offers a custom SECURITY file:

The easiest way to set up a SECURITY file is via the UI. Go to the Security tab and click on the Setup a security policy button. Click on the Start setup button in the new window.

GitHub provides a default Markdown template, but of course, you can choose to change the format and the content. The important part is to tell users how they should report security vulnerabilities.

The newly-created file appears in Security  View security policy. Here’s a sample in Asciidoctor format.

If your project is good, other projects will likely use it. The project may be cited in academic works, even more so if it’s of an academic nature itself. The CITATION file allows you to answer the following questions:

The standard CITATION format is the Citation File Format, proposed by GitHub:

You can non only choose how to format the citation but also cite an alternative source, e.g. a related academic article.

Again, GitHub’s UI helps one create a CITATION.cff file. When you create one, it offers you to add a sample, which you can edit to your heart’s content.

After adding the file, a new Cite this repository link appears on the right sidebar. You can choose which format you want to copy, APA or BibTeX when you click it.

Last but not least, let’s look at how to configure sponsorship. If you provide value to third parties via your Open Source project, it makes sense to let them reward you. Note that you shouldn’t count on it, though, or you’re in for a surprise.

GitHub allows displaying sponsorship options via a dedicated FUNDING.yml in the .github repository. Once more, the UI helps. Go to Settings and click on the Set up sponsor button. It opens the usual window to create a new file with a template. Here’s how I changed it:

The preview tab validates your input.

In this case, the validation fails by telling that user nfrankel (me) didn’t enroll in the GitHub sponsors program.

A new "Sponsor this project" section appears on the right sidebar on the repo’s homepage.

GitHub offers multiple ways to improve your repository’s display and usability. A LICENSE and a README should be mandatory for any repository you want to share with others. Besides them, you should provide the other beautifications listed in this post.