Notes on GitHub Pages

Notes on GitHub Pages related to the OpenDRR Project

(early draft, work-in-progress)

Table of Contents Informational Architecture (Drafts) (February 2021 Demo) Structure under https://opendrr.github.io/ Design Themes / templates 1. canada-ca/canada-ca-jekyll-boilerplate 2. jekyll-info-viz Convert research papers from AsciiDoc format to HTML GitHub Pages Other sample GC websites Quick references Future explorations

Informational Architecture (Drafts)

See README.md and PDF files in https://github.com/OpenDRR/opendrr-platform/tree/master/documentation/GitHub-Pages

• opendrr-platform/Information Architecture-Draft-v1.0.pdf at master · OpenDRR/opendrr-platform
• opendrr-platform/Informational Architecture-Draft-v1.1.pdf at master · OpenDRR/opendrr-platform

These were designed by Michael and Joost in around mid-September 2020.

(February 2021 Demo) Structure under https://opendrr.github.io/

There are three types of GitHub Pages sites: project, user, and organization. (from GitHub Docs)

• / (organization site: https://github.com/OpenDRR/opendrr.github.io)
• /data (project site: https://github.com/OpenDRR/data)
• /documentation (project site: https://github.com/OpenDRR/documentation)

There is a possibility of namespace clashing:

• https://www.freecodecamp.org/news/publishing-an-organization-homepage-on-github-pages-347dbd700f4e/
• https://stackoverflow.com/questions/25396383/does-a-folder-in-my-user-site-conflict-with-a-project-site

but fortunately, as long as we are careful, all these sites can co-exist together nicely, giving the end users a unified experience.

Design

• Figma (See Data Dissemination Strategy)

Themes / templates

1. canada-ca/canada-ca-jekyll-boilerplate

Pulls in wet-boew/gcweb-jekyll as a remote theme.

Based on GCWeb [FIXME]

• Working examples - Canada.ca

Confused? See What is the difference with the wet-boew/gcweb-jekyll variant? · Issue #1 · canada-ca/canada-ca-jekyll-boilerplate

Demo: https://wet-boew.github.io/gcweb-jekyll/

2. jekyll-info-viz

This is being used because of the added Leaflet integration to display mobile-friendly interactive maps.

This was (sort of) forked from wet-boew/gcweb-jekyll@e0551ba which is extended to create https://opendrr.github.io/data, for example.

Convert research papers from AsciiDoc format to HTML GitHub Pages

https://github.com/OpenDRR/documentation/blob/master/docs/opendrr-platform.adoc

The jekyll-asciidoc to the rescue! It works pretty well! Unfortunately, it is not one of GitHub’s whitelisted plugin, see https://pages.github.com/versions/

Potential solutions:

• https://github.com/marketplace/actions/jekyll-actions (Docker)
• https://github.com/limjh16/jekyll-action-ts (JavaScript)

Some potential solutions:

• asciidoctor-ghpages-action/asciidoctor-ghpages.yml at main · manoelcampos/asciidoctor-ghpages-action
• https://go-team.pages.debian.net/, https://salsa.debian.org/go-team/go-team.pages.debian.net (Makefile calling asciidoctor)

Other sample GC websites

• https://digital.canada.ca/, source: https://github.com/cds-snc/digital-canada-ca (comment by Joost)
• https://eccc-msc.github.io/open-data/readme_en/, source: https://github.com/ECCC-MSC/open-data (comment by Joost)

Quick references

Jekyll:

• Quickstart | Jekyll • Simple, blog-aware, static sites
• Directory Structure | Jekyll • Simple, blog-aware, static sites
• Layouts | Jekyll • Simple, blog-aware, static sites
• Testing your GitHub Pages site locally with Jekyll - GitHub Docs

Future explorations

• Netlify CMS
  • Netlify CMS requirements · Issue #7 · canada-ca/canada-ca-jekyll-boilerplate
  • Working with Netlify CMS and GitHub Pages – SB-PH
  • https://www.reddit.com/r/webdev/comments/8r9rdl/user_auth_with_netlify_without_identity/
  • https://github.com/vencax/netlify-cms-github-oauth-provider
  • https://cnly.github.io/2018/04/14/just-3-steps-adding-netlify-cms-to-existing-github-pages-site-within-10-minutes.html
• Quire (Getty Publications) | Getty Publications | The Getty (looks very pretty, but more for arts-related electronic publications?)
  • https://github.com/thegetty/quire
  • Tutorial and documentation: https://quire.netlify.app/
• Hugo:
  • Host on GitHub | Hugo
  • Hugo setup · Actions · GitHub Marketplace
  • wowchemy/starter-research-group: 👥 Create a stunning Research Group Website with Wowchemy and Hugo
  • Wowchemy Research Group
  • Write from your sofa with the built-in CMS | Wowchemy: Free Website Builder for Hugo
  • Create a site with Github/Gitlab | Wowchemy: Free Website Builder for Hugo