Skip to content

Latest commit

 

History

History
624 lines (410 loc) · 17.7 KB

slides.md

File metadata and controls

624 lines (410 loc) · 17.7 KB
Raw

Personal & Professional Websites w/ GitHub Pages

CIDR

https://sul-cidr.github.io/gh-pages-2021/

Before we begin...

Please sign in for this workshop at:
https://signin.cidr.link/Websites_with_GitHub_Pages/

When you've submitted the sign-in form, please keep the browser tab open on the evaluation form as a reminder to complete it when the workshop is over.

This workshop will introduce you to using the free GitHub Pages service to host website and web pages online.

We will take you through creating a GitHub account and a GitHub Pages site, and then show you how to create simple but useful web pages you can use to create an online presence for yourself or for a project or team.

No prior experience is assumed or expected, and no special tools or software is required.

Overview

  • Websites and Web Pages
    • HTML, CSS, and JavaScript
    • Static Sites vs. Dynamic Sites
  • Git, GitHub, and GitHub Pages
    • Concepts and Services
    • Creating a GitHub Account
  • Writing and publishing HTML pages
    • Publishing from GitHub Pages
    • A Self-Contained Web Page
    • A Single-Page Résumé Site
  • Static Site Generators, Markdown, and Jekyll

HTML, CSS, and Modern Web Pages

  • The anatomy of a web page:
    • Content Layer (HTML)
    • Presentation Layer (CSS)
    • Behaviour Layer
      (ECMAScript, more commonly known as JavaScript)
    • Other resources (images, media etc., potentially data)
  • "Static" by nature
    • Clients (web browsers) download the resources
      and render the page on the user's computer

Static vs Dynamic Websites

  • Dynamic Websites

    • A web application creates the resources (HTML) on-demand, when a user request is made
    • Typically (though not always) involves a database server
    • Can be updated in real time, while running
    • Examples include CMSs such as WordPress, Drupal, MediaWiki

  • Static Sites

    • Resources are created in advance of user requests and are delivered to users exactly as stored
    • Updates require that some or all of the pages are modified/replaced/recreated
    • No special server-side software required
    • Resources can be created by a Static Site Generator
  • "Static" ≠ non-interactive!

::: Dynamic sites involve running a some software (PHP, Python, Ruby etc.) on a server somewhere

Advantages of Static Sites (I)

  • Security
    • Fewer (or essentially no) moving parts mean an almost non-existent attack surface
  • Ease of Hosting
    • The simplest possible hosting requirements mean the site can be hosted almost anywhere
      and at little to no cost
  • Ease of Maintenance
    • Nothing needs regular maintenance, security patching, etc.

Advantages of Static Sites (II)

  • Portability and Preservation/Archiving
    • Static sites are trivial to backup, to move to new locations, and to put under version control
  • Speed and Scalability
    • The simplicity with which static sites can be hosted also means that pages can be served
      as fast as they can be requested
  • Simplicity and Control
    • With fewer moving parts and less technology between the author and final page, it's easier
      to feel a sense of ownership and control

:::

  • Static sites also require the author to think more in terms of simplicity which generally results in better sites (for most of the above reasons)

Disadvantages of Static Sites

  • Some things are more difficult and/or require third-party services and solutions
    • Site search
    • Commenting
  • Some things just require dynamic content
    • User-specific content
    • Working with large datasets

::: say something about widgets?

  • interactive elements
  • maps

Static Site Generators

  • The principle behind SSGs is to separate content and layout/styling ("themes")

    • This has the major advantage of avoiding repetition, and allows authors to focus on
      the content without distractions

  • Typically content is created in Markdown files

  • The SSG combines the content files with a template

    • This step create the static HTML (and CSS, JavaScript etc.) files which comprise the static site

  • Popular SSGs include Gatsby, Hugo, Eleventy, and Jekyll

:::

git

GitHub

GitHub

git

  • Distributed Revision Control System
  • Created by Linus Torvalds to support Linux kernel development in 2005
  • Completely free and open-source (GPL-2.0-only)
  • Has a reputation for being kinda gnarly
Git

::: At the start of 2020:

  • 2.8 million l-o-c
  • ~900,000 commits

  • 27,000 contributors

Some git concepts

  • Repositories

    • For our purposes, a repository (repo) is a collection of source files that are tracked under version control.
    • Repositories can be (are) distributed -- meaning that multiple copies can exist in multiple locations

  • Commits

    • A commit is a collection of content representing the state of the repo at a given point
    • Commits are annotated with commit messages, which typically (should) describe the changes represented by the commit

Note: This is heavily simplified and omits several important concepts needed to use git effectively on your local computer.

::: This is some notes.

GitHub

  • Repo hosting and additional services based around git
    • Regular remote git commands
    • Issues, PRs, Wikis, GitHub Actions (CI/CD), and much more
    • GitHub Pages
  • Launched in 2008, it was acquired by Microsoft in 2018
  • Provides free and premium services
  • At time of writing, GitHub claims > 60 million users and ~240 million repositories

GitHub Pages

  • Offers free static web hosting for public GitHub repositories
    • Can serve HTML and related files directly from a repository, but can also integrate
      SSGs to build sites from content in a repository
  • Provides addresses of the form <gh-user>.github.io/<repo-name>
    • Can use custom domain names purchased and registered elsewhere
  • Automatically creates free TLS (https) encryption certificates

Limits and Limitations of GitHub Pages

  • Static sites only!
  • Maximum file size: 100 MB
  • Maximum site size: 1 GB
  • Bandwidth limit: 100 GB / month (soft limit)
  • Build limit: 10 builds / hour (soft limit)
  • Public sites and repositories only (on free plans)

Creating a GitHub Account

  • Navigate to github.com and create an account

    • Enter the email address you want to use and choose a password
    • Complete the email verification process
    • "Skip Personalization" for now

  • Complete the README.md repo

    • If you already had a GitHub account, create the repo <gh-user>/<gh-user>,
      and create a README.md file
    • Edit the text a little, and make your first commit!
    • <gh-user>/<gh-user> is a special repo -- the contents of README.md will
      appear on your GitHub profile page

Let's create some websites!

Create a Repository

  • Create a new repository with the name <gh-user>.github.io

    • If you already have a repo with this name, create a new repo with whatever name you like, but be ready to make changes later on
    • Select "Add a README file" -- this will make it easier to get started

  • Create a new file (Add File → Create new file) called index.html

    • Add some obligatory "Hello World!" text

  • Navigate to Settings and then Pages, and see that your site is published

  • Visit https://<gh-user>.github.io/ and see that your site is live!

The Simplest Possible Web Page

Copy-and-paste this simplest possible HTML document over the top of the index.html in your repo, and change the text. Commit the new version, and wait for GH-Pages to deploy your new page.

  
    <script type="text/template">
      

        
          <title>Your title here...</title>
        

        
          Your content here...
        
      
      
    </script>

The Simplest Possible Web Page

Copy-and-paste this simplest possible HTML document over the top of the index.html in your repo, and change the text. Commit the new version, and wait for GH-Pages to deploy your new page.

  
    <script type="text/template">
      
        
        
          <title>Your title here...</title>
        

        
          
Welcome to my page
 
          Your content here...
        
      
      
    </script>

A Single-File Example

Let's create a more interesting example.

  • Use Ctrl + U or ⌘ + U to "View Source" and take a look at the HTML
  • Copy-and-paste the entire contents over the top of your index.html in your repository
  • Commit, and wait for the deploy

Using dev. tools

  • Hit Ctrl + Shift + I or ⌘ + Shift + I
  • Use the "Elements" tab (Chromium-based browsers) or the "Inspector" tab (Firefox) to take a look at the page
  • Change a few things!

A One-Page Résumé Site

Editing with VS Code Web

  • From your repo page on github.com, press the . key
    • The URL is the repo URL with github.dev in place of github.com
  • Change some text in the index.html file, and one or more of the colours in style.css, then use the Source Control panel to create a commit.

GitHub Pages and Static Site Generators

  • You can use any SSG with GitHub Pages
    • Once the pages are built (on your laptop or some other way) they are just static .html pages
      (and related resources), and can be uploaded to a GitHub Pages-enabled repository just like
      the files we've been using so far.
  • GitHub Pages has Jekyll built in
    • This makes it considerably easier to work with.

Making a site with Jekyll (I)

  • Delete your <gh-user>.github.io repo (or rename it if you'd like to keep it around)
    • Settings → Delete this repository
  • Create a new repository with the same name
    • Go back to your profile page at https://github.com/<gh-user>, then Repositories → New
  • Create a new index.md file, with the contents
---
title: Home
---

[Home](index.md)

# Welcome to my personal website!
  • Commit, wait for deploy, and check out your site

Making a site with Jekyll (II)

  • Create a new file called about.md:
---
title: About
---

[Home](index.md) | [About](about.md)

# About me

Something about me goes here.
  • Update index.md to have the extra link [About](about.md) too

Front-matter and Themes with Jekyll and GitHub Pages

  • Create a new file _config.yml:
title: <Your Name Here>
description: Personal site for <Your Name>
remote_theme: pages-themes/hacker@v0.2.0
plugins:
  - jekyll-remote-theme
  • Commit, wait for deploy, and check out your site

Working with local files

If you do a lot of this, or if you want to get more into using git and GitHub for more than just simple static site or two, at some point you're going to need to install git on your computer and get used to keeping your local repository in sync with the remote repository (on GitHub or perhaps elsewhere).

Further Resources (I)

Further Resources (II)

Further Resources (III)

Thanks! CIDR

Please fill out the evaluation form for this workshop at: https://evaluations.cidr.link/Websites_with_GitHub_Pages/