A GitHub.io page is a great way to have a portal for the various open source projects your organization maintains or about how to use products from your organization. Some great examples of GitHub.io projects out there include:
All of the above have some things in common, that I think are important:
- The branding is consistent(ish) with company guidelines, so the experience isn’t tooooo dissonant with the main pages
- The salesy part of the branding has been stripped out
- The experience is putting useful content for developers right up front
- Most assume some knowledge of scripting, consuming APIs, and other technical needs
- They showcase and include information to projects
- Projects from multiple accounts are included (even projects owned by other organization if they help put developing more open source projects out there)
Taking all this into account, let’s make a page! To get started, first create a project in your GitHub account with the url of <accountname>.github.io.
Create an index.html page in there (even if it’s just a hello world page). At this point, you’re just writing standard html. You can have standard tags like H1, H2, etc – and import a css elements from another place.
I really like is displaying cards for your GitHub projects. One project that I like to use (I must have tested 30-40) is GitHub-cards. To use that you’ll need to enable Java, as you can tell from the .js. Then you just include a line to display that card, replacing the data-github field contents with the username/projectname of any projects you want to include, as follows (e.g. for the GitHub user/org name jamf and the GitHub project name of KubernetesManifests):
<div class="github-card" data-github="jamf/KubernetesManifests" data-width="400" data-height="" data-theme="default"></div>
<script src="//cdn.jsdelivr.net/github-cards/latest/widget.js"></script>
One final note, many an organization has a standard css they want to be used when building new web properties, including something like a GitHub site. You can leverage these by calling them out in the header as follows:
<link href="https://www.jamf.com/css/main.css" rel="stylesheet" type="text/css" media="screen">
According to how much is involved in how a given CMS mucks up code, you might have a lot of tweaking to bring elements in and consume them to your orgs spec, but it’s much easier than sifting through rendered source to figure it out on your own. Once published, go to the account name.github.io (in this example, jamf.github.io) and viola, you have a new page!