How to publish your lecture notes

A GitHub vs Moodle showdown

Vicky Scowcroft

Department of Physics, University of Bath

Overview

• What is GitHub?
• What is GitHub pages?
• GitHub vs Moodle
• How it works in practice

What is GitHub?

github.com is an online hosting service for software development and version control

— Wikipedia: GitHub

Why is this useful for lecture notes??

Why is this useful?

• Version control
  • Keeps all previous versions
    • (assuming you’ve uploaded them…)
  • Can ‘roll-back’ to previous versions.

• Collaboration

  • Can collaborate without file editing clashes.

  • Pick and choose which changes to keep.

Basic intro to GitHub here

Intro to GitHub pages here

Why use GitHub when we have Moodle?

Github pages vs Moodle

GitHub pages	Moodle
Externally visible	Visibility limited by course access
Initial set-up can be faffy	Initial set up done centrally
Built-in version control	Updates remove previous version1
Easy2 to make incremental changes	Changes require re-uploading everything

¹ I think you can roll-back to the latest Moodle back-up??

² Incremental changes are usually easy on GitHub, until something goes wrong. Then Stack Overflow is your best bet.

Setting up

Assuming you already have an account on GitHub (or Bath GitHub) and you’ve set up your credentials:

Step	Command
1st time only: Create repository	git init
To get the most up to date remote version: Pull the remote repository to your computer	git pull
Create/edit content
Add files you want to commit	All files with changes: git add -A Individual files: git add $filename
Check what’s going to change	git status
Commit your files to be uploaded and say what your changes are	git commit -m "your message here"
Push files to GitHub	git push

Publishing using gh-pages branch

• Needs an extra step to publish after upload
• Gives more control over what is published (and when)

• 1^st time only:

  • Set up gh-pages branch

  • Clone this branch into a new folder:

git clone -b gh-pages $repo-path book-output

$repo-path is the location of the repository on github, e.g. https://github.com/your_user_name/lecture_notes.git

• Then:

cd book-output
cp -r ../_book/* ./
git add --all *
git commit -m "Update the book" || true
git push -q origin gh-pages

assuming your bookdown book is in a folder called _book

Publishing using docs folder

• Will automatically update content every time you commit changes
• A bit less control over what is published (and when)

• Set up GitHub pages to generate automatically from the docs folder

• Rename/copy your _book folder to docs
• git add, commit, and push the main repository as normal.

GitHub hosted examples

• My guide to lecture notes with bookdown
  • Living document - suggestions/edits welcome!
• PH40112 Relativistic Cosmology - 2019/20
  • My first attempt at bookdown lecture notes (during Covid…)

How to publish on Moodle

1. Compress your _book file to _book.zip
2. Upload the file to Moodle
3. Unzip the file
4. Set index.html as the main file

• Should now see a link to your document on Moodle.

• PH40112 Relativistic Cosmology 2021/22: This is not externally accessible. . . .

What’s annoying about this?

• You have to replace the whole document to make any changes.
• Doesn’t seem to be a way to update incrementally (very easily).

Summary

• Version control is good for you

• Using GitHub is easier than you may think
• https://github.com/vickyscowcroft

• If you get stuck, someone on Stack Overflow has probably already solved the same problem