Publish GitHub Pages

Publishing web-based materials is easy with GitHub Pages, a free service for hosting static websites useful for project documentation and personal portfolios. The personal portfolio is typically built using a repo with the name [username].github.io. Subpages are built using [username].github.io/[reponame] where [reponame] can is the name of a repo owned by [username]. The [username] can also be a GitHub Organization.

The resources below cover the basics of GitHub Pages and provide links to my published pages and more detailed guides and tutorials.

• My GitHub Pages
  • My Documentation GitHub Pages
  • QR Codes for Github Pages
• GitHub Pages References
• Additional Pages
  • Embed Objects in GitHub Pages
  • Automate with GitHub Actions

My GitHub Pages

My main GitHub Page byandell.github.io, with source at https://github.com/byandell/byandell.github.io, was modeled on (forked from) https://github.com/barryclark/jekyll-now. This has cool features like blog pages.

In addition to my main GitHub Page, I have several subpages that are built separately in different GitHub repos. Note that the landmapyr page is built within the byandell-envsys GitHub organization, which I created to organize my environment systems research projects.

• byandell.github.io/Documentation (source): Documentation of Digital Tools (whole repo)
• byandell.github.io/geyser (source): Geyser Shiny App with Modules (docs/ folder)
• byandell-envsys.github.io/landmapyr (source): Land Mapping Package (docs/ folder)
• byandell.github.io/esiil-stars (source): ESIIL Stars Training Notes (whole repo)
• byandell.github.io/ESIIL (source): ESIIL Research (docs/ folder using MkDocs)

My Documentation GitHub Pages

I developed Document Digital Tools to serve as a reference for the Digital Tools I use. In the process, I learned how to use Just-the-Docs as the theme, which includes many useful navigation features. It interprets README.md files in folders as top-level pages, with the README.md in the top-most folder displayed as the homepage. One mistake I made was that putting YAML front matter in a README.md such as for navigation order (nav_order), requires adding a permalink, which forces Jekyll to use that page as the top-level index page. The corrected front matter, say for the top README.md:

---
title: "Documentation for Digital Tools"
nav_order: 0
permalink: /
---

I also learned that using title: and parent: was a useful way to create a navigation hierarchy.

QR Codes for Github Pages

I generated a QR Code that points to my profile page https://byandell.github.io using Adobe Express.

Warning: Be careful generating QR codes. Do you really need more than one? I only have one, and make sure that relevant links to my material are easily findable from my profile page.

You cannot add an image directly to your wallet, but you can use third party apps to create a pass that is added to your wallet. I used Pass4Wallet. other choices include

• Add a QR code to Apple Wallet (QRCG)
• How to add a QR code to Apple Wallet (qrcodedynamic)

GitHub Pages References

• ESIIL Data Short Course: Create your own portfolio webpage
• The Least You Need to Know About GitHub Pages
• GitHub Pages Documentation
• Publish Your Project Documentation with GitHub Pages
• GitHub Page Themes
• Jekyll Now
  • Build A Blog With Jekyll And GitHub Pages
  • Other forkable themes
• GitHub Actions
• MkDocs (advanced topic)
  • Materials for MkDocs: Publishing your site
  • Deploying your docs
• Resolving Git Push for CI/CD Workflows (TutorialPedia)

---

Table of contents

• Embed Objects in GitHub Pages
• Automate with GitHub Actions