Resources to help you learn GitHub Pages

September 10, 2020 by Quentin Read , Kelly Hondula , Rachael Blake

The SESYNC Cyber Team has compiled some resources, including tutorials and examples, on how to use GitHub Pages. Most of them are based in Markdown and Jekyll. Markdown is a “lightweight markup language,” meaning a way to write a text document with minimal formatting codes that can be rendered into a document such as a webpage. Jekyll is a “gem” written in the Ruby language (to be cute, but confusing, they call packages in Ruby “gems”) that turns documents written in Markdown into (static) HTML sites with nice layouts. It isn’t necessary to use Markdown and Jekyll to use GitHub Pages, but Jekyll has built-in support for GitHub Pages so everything integrates pretty well. This means GitHub takes care of converting your human-readable files (like Markdown) to HTML, including all of the relative link paths to navigate your website based on configuration files. Hugo is an alternative to Jekyll.

Pros and Cons of GitHub Pages

Pro

• Free, no ads!
• You can customize it however you want.
• You can use your page to demonstrate your skill in website creation to potential employers, because they can look at the underlying code on your repo.

Con

• It seems like the main weakness of GitHub Pages and associated templates is that they don’t look that great on smartphone screens. There might be some ways around this but it is something to be aware of.
• It takes more initial learning time than point-and-click interfaces for creating sites, especially if you really want to customize things.

Tutorials for beginners

• GitHub’s “official” guide to Pages
• GitHub’s help page on setting up Jekyll with Pages
• SESYNC’s advanced git lesson, including a section on Pages
• Karl Broman’s tutorial (a favorite of Kelly H.’s that may be somewhat outdated by now)
• Thinkful’s guide to GitHub Pages
• Jonathan McGlone’s tutorial
• RMarkdown website tutorial
• Information about using Hugo as a website framework and options available

Some more basics & tips

• Tips from Berkeley on making your website accessible (FYI: don’t use “click here!” links)
• Explains the difference between User (my-github-username.github.io) and Project (my-github-username.github.io/my-awesome-project) pages

Templates for personal sites

These are focused on academic personal sites but could be used for other purposes. Lots more templates are out there.

• https://academicpages.github.io (Jekyll based template)
• https://sourcethemes.com/academic/ (Hugo based template)

Example sites that use GitHub Pages

• The SESYNC Cyberhelp website!
  • link to site
  • link to source code on GitHub
  • Check out the readme document for the structure and contributing instructions for more about how we modify content.
• The Palmer lab group website (made by Kelly H.)
  • link to site
  • link to source code on GitHub
  • Kelly H notes: We copied a template from another lab website and contacted them first about using it. because licensing is kind of opaque for this stuff.
• Quentin’s personal site (uses the academicpages.github.io template)
  • link to site
  • link to source code on GitHub
• Allan lab group website. This academic research group site also contains some information on how the site was made, and how to get started.
  • link to site
  • link to source code on GitHub
• Teacups, Giraffes, and Statistics: A statistics tutorial in R, site built without Jekyll
  • link to site
  • link to source code on GitHub
• Biosystems Analytics Lab: An academic research group site that uses the Hugo Academic template linked to above
  • link to site
  • link to source code on GitHub