9. Publishing from GitHub

9. Publishing from GitHub#

GitHub pages

Yaml Frontmatter#

GitHub will publish repositories containing markdown as web pages, automatically.

You’ll need to add this content:

   ---
   ---

A pair of lines with three dashes, to the top of each markdown file. This is how GitHub knows which markdown files to make into web pages. Here’s why for the curious.

import os

try:
    from google.colab import drive  # type: ignore

    drive.mount("/content/drive")
    drive_dir = "/content/drive/MyDrive"
except ImportError:
    print("Not running on colab")
    drive_dir = os.path.join(os.getcwd(), "drive", "MyDrive")
    os.makedirs(drive_dir, exist_ok=True)

print(f"Drive dir: {drive_dir}")

git_dir = os.path.join(drive_dir, "learning_git")
working_dir = os.path.join(git_dir, "git_example")

if os.path.exists(working_dir):
    print(f"Git example directory: {working_dir}")
    os.chdir(working_dir)
else:
    print("Start from the beginning")

Not running on colab
Drive dir: /mnt/nvme1n1p2/home/yj.lee/workspace/projects/lecture/book/lectures/softeng/vcs/drive/MyDrive
Git example directory: /mnt/nvme1n1p2/home/yj.lee/workspace/projects/lecture/book/lectures/softeng/vcs/drive/MyDrive/learning_git/git_example

%%writefile test.md
---
title: Github Pages Example
---
Mountains and Lakes in the UK
===================

Engerland is not very mountainous.
But has some tall hills, and maybe a mountain or two depending on your definition.

Overwriting test.md

%%bash
git commit -am "Add github pages YAML frontmatter"

[main 964c673] Add github pages YAML frontmatter
 1 file changed, 5 insertions(+), 2 deletions(-)

The gh-pages branch#

GitHub creates github pages when you use a special named branch. By default this is gh-pages although you can change it to something else if you prefer. This is best used to create documentation for a program you write, but you can use it for anything.

os.chdir(working_dir)

%%bash

git checkout -b gh-pages
git push -uf origin gh-pages

Switched to a new branch 'gh-pages'

remote: 
remote: Create a pull request for 'gh-pages' on GitHub by visiting:        
remote:      https://github.com/chu-aie/github-example/pull/new/gh-pages        
remote: 
To https://github.com/chu-aie/github-example.git
 * [new branch]      gh-pages -> gh-pages

branch 'gh-pages' set up to track 'origin/gh-pages'.

The first time you do this, GitHub takes a few minutes to generate your pages.

The website will appear at http://username.github.io/repositoryname, for example:

http://chu-aie.github.io/github-example/

Layout for GitHub pages#

You can use GitHub pages to make HTML layouts, here’s an example of how to do it, and how it looks. We won’t go into the detail of this now, but after the class, you might want to try this.

%%bash
# Cleanup by removing the gh-pages branch
git checkout main
git push
git branch -d gh-pages
git push --delete origin gh-pages
git branch --remote

Switched to branch 'main'

Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

To https://github.com/chu-aie/github-example.git
   7ffd228..964c673  main -> main

Deleted branch gh-pages (was 964c673).

To https://github.com/chu-aie/github-example.git
 - [deleted]         gh-pages

  origin/main
Contents