GitHub Pages

Why use version control?

  • Everyone uses some version control. (e.g. by copying the document with a date suffix).

  • There are many version control systems (VCSs).

  • git is the de-facto standard these days. It is open source and free. It is integrated in many tools.

  • GitHub is the most popular cloud-based hosting service for git repositories with many extra features.

  • In this session we will use git only via the web-site of GitHub.

GitHub Account

  • If you don't have an account yet on GitHub then create one now.

  • It should be personal. It will remain with you for your life. (or the life of GitHub)

  • It should not be related to your current educational institute or workplace or this presentation or course.

  • My account is szabgab on GitHub. It is my nickname almost everywhere on the Internet. It is even the address of my web site.

Repositories

  • On GitHub you can store as many git repositories as you like. They can be either private or public.

  • The names of the repositories are arbitrary.

  • https://github.com/USERNAME/REPO-NAME

  • https://github.com/ORGANISATION/REPO-NAME

  • Some repository names have special meanings.

  • USERNAME

  • USERNAME.github.io

For me they are

GitHub Avatar

  • Update your profile, add information about yourself.

  • Add a picture or an avatar of you to make your account more recognizable.

  • Your profile / Edit profile / ...

  • The big text comes from the README.md file of the szabgab/szabgab repository.

Setting up GitHub page

  • Create a GitHub repository called USERNAME.github.io (using your own USERNAME).

  • For user szabgab it is szabgab.github.io.

  • Make the new repository public so everyone will be able to see the source.

  • Check the "Add a README file" checkbox.

  • Check the Actions tab to see the process generating the web site.

  • Visit https://USERNAME.github.io (it may take a few minutes to update)

  • For user szabgab it is szabgab.github.io.

  • For GitHub Organizations it is exactly the same process.

HTML - view source

  • Web sites are built using HTML.
  • Look at the source of the page. That's HTML. We don't want to write that.
  • So we'll use Markdown and an some tool that will convert Markdown to HTML.

GitHub page with Jekyll

Markdown Links

Markdown

  • Titles: One or more # followed by the the title

  • Bold ** on both sides

  • Italic _ on both sides

  • Horizontal separator ---.

  • Link to some other site. e.g. to the slides.

  • Unordered list. *

  • Ordered list (both with ordered numbers and with 1.-s)

  • Add image from other site ![](http://www.adelaidezoo.com.au/wp-content/uploads/sites/2/2016/03/Fu-Ni-7.jpg)

  • Upload an image and show it.

  • Use the img HTML element to set the size of the image.

![my ant](little-black-ants.jpg)

  • Table

  • Verbatim with back-ticks.

  • Inline with one-tick.

  • Multi-line with 3-ticks. Add also programming language for highlighting.

  • Indenting 4 spaces also works.

Add page

  • Create a file called about.md.
  • Visit https://USERNAME.github.io/about
  • Show how to link to it from the main page.
# Hello Markdown World

## Subtitle

* bullet
* points
* and [home](/)

1. Numbered
1. List
1. Autoincrement

Customized 404 Page not found

  • Visit a page that does not exist.
  • Create the 404.md file to provide custom error message.

Jekyll themes

  • themes
  • Create _config.yml with
theme: jekyll-theme-cayman

Themes - layout

Site-wise configuration

  • In _config.yml

In the _config file we can add a field called description:. It will provide the content for the subtitle of the header.

description: Some text

theme: jekyll-theme-cayman
title: "GitHub Page of Gábor Szabó"
show_downloads: false

Page-specific configuration - frontmatter

---
title: About the szabgab page
---

JavaScript code


<div id="text"></div>

<script>
document.getElementById("text").innerHTML = "Text added by JavaScript code";
</script>
  • One can include plain HTML in the md file. So include script tags.
  • The code should come at the end to have the DOM available already.

Load jQuery and add jQuery code

<script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
<script src="/demo.js"></script>

<div id="text"></div>



$().ready(function() {
   $("#text").html("Text added by jQuery code.");
});

When you change the JavaScript file, make sure it is reloaded! Browser cashing can cause you a bad day.

Add a JSON file, load it with jQuery and display the content

<script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
<script src="/json.js"></script>

<div id="text"></div>



$().ready(function(){
    $.getJSON( "/data.json", function( data ) {
    console.log(data);
    $("#text").html(data["text"]);
  });
});

{
   "text" : "Text supplied in the JSON file"
}

HTML pages

  • Create a file called about.html.
<h1>Hello HTML World</h1>

Some sample text.
  • Note: the .html files take precedence over the .md files!

Examples

Rename repository

  • Rename repository so I'll be able to demo this later as well.
  • Show how to access the web site now.

Open Issue

  • Show how to open an issue on the repository with a link to your site and repository.
  • Show with my own site.

Add table of people

  • Take the data from the issue and add it to the table listing the web sites.