Tips for GitHub Content Discoverability: GitHub SEO

SEO, or Search Engine Optimization, is a dirty phrase to some people, but that’s usually because they don’t understand the difference between making your content easier to find and shoving it down people’s throat. And that’s probably because the kind of SEO they’ve seen focuses on the latter. 

There are ways to implement SEO that are actually helpful for readers and not ill-intended. Here are some tips to make your content on GitHub more discoverable with GitHub SEO. 

Use GitHub Organizations

For example, let’s say you have a personal GitHub ID that contains your personal projects, but you’re also involved in a volunteer group. Rather than create a repository for your volunteer group in your personal account, you can create a new GitHub organization for your volunteer group.

Organizations on GitHub are like personal IDs, but they can be more descriptively named because they aren’t a personal handle. And you can “own” more than one. Because Microsoft owns GitHub, let’s use one of their famous example companies, Contoso, to further illustrate this point.

Imagine you’re the OSS community manager for Contoso, and you need to share a number of guides and code samples. You could use the following naming structure: 

github.com/contoso (organization)

  |- Guides (repo)

      |- Using_Contoso_Widgets (folder)

  |- Samples (repo)

      |- Contoso_Widgets_SDK (folder)

But if someone goes searching on GitHub, or even at the top level of the Contoso organization on GitHub, for “Contoso Widgets” for example, it may not register any results, simply because there’s no repository with “widgets” and “contoso” in the name. 

In this case, you will likely receive a message: “we couldn’t find any results matching the search org:contoso contoso widgets.“

A better strategy would be to use the following naming structure:

github.com/contoso-guides (organization)

    |- Using_Contoso_Widgets (repo)

github.com/contoso-samples (organization)

    |- Contoso_Widgets_SDK (repo)

GitHub SEO Benefits

There are a few quick benefits to implementing GitHub SEO best practices.

1: You’re now using the search term in the repository name, not in the name of a subfolder. This makes the content easier to find because it will show up in the primary search.

2: Google’s algorithm weights content (to an extent) by the depth of the folder.

• github.com/contoso/guides/using_contoso_widgets puts it four folders deep.
• github.com/contoso-guides/using_contoso_widgets puts it three folders deep.

It’s not a huge difference, but Google will index the content faster and consider it more relevant to “contoso widgets,” giving it a better chance of appearing higher in the Google search results.

But you might be asking: “How will customers find their way from the guide to the SDK or vice versa if they’re not bunched together under one organization?” 

That’s a good question, but you can easily remedy that by linking from the readme files to related repos, and not just as a bullet point at the bottom. Every time you mention the SDK in a guide, link to the SDK repo. 

Start Using GitHub SEO

As you can see, none of this is black-hat SEO; this isn’t one trick to beat your competition. It’s just good practices that help ensure more people searching for the content you share on GitHub can actually find it easily. So next time you’re planning to share stuff on GitHub, consider using organizations in your architecture.