gh pages instruction

Instructor notes

Go into settings in your repo Two options: http://yourusername.github.io/ http://yourusername.github.io/projectname/ If you prefer the first, name your repo username.github.io For simplicity later on, let’s everyone pick the second option for this workshop First apply GH pages with “supported” theme (minimal theme) They can pick their own theme Add description and website Can see green check mark in commits Find the gh repo for your theme. Gives directions to update config. Add title and description in config file Remove template content from readme.md Add some content using markdown. For example, a list. Some notes. A few headings. What are some limitations of using a supported theme?

• Having one long page is not going to work. We want separate pages for each module. “Supported” themes make it easy to publish a page. However, you have little control. I can use any Jekyll theme. However, too many files to use the web interface. So I will demo command line here.

Let’s use the Jekyll theme “minimal-mistakes” Find URL for quick start guide and GH repo.

Navigate to repo created with issues, projects, etc. We’re going to clone from master with HTTPS Open terminal cd Desktop mkdir modules cd modules git clone URL ls cd projectname ls ls –a

• Remove unnecessary files
• rm –R (hidden files) git checkout –b gh-pages git add . git commit –a –m “Creating my gh-pages site” git push (data modules URL clone) gh-pages (if I want to have a clean commit history I can do that too. Can you guess how?) Delete branch on GitHub rm –r –f .git git add . git commit –a –m “Fresh git versioning” Can we push it? No. The branches were saved in the git file. We need to do that again. git checkout –b gh-pages git push (data modules URL clone) gh-pages Is this OK with the license? Read: yes. Let’s add a readme to provide attribution anyway

Alternatively, fork Cannot clone. Can download but cannot upload via GitHub interface; maxes out at 100 files. (Optional: delete same files from master, just one or two) (Forking is typically used when you’re going to be doing pull requests or otherwise interacting with the original repository or representing the files origins. In this case, it’s not needed) Does the URL work? No. Needs gh-pages branch. Then create gh-pages branch from master Then delete other branches except gh-pages. Use branches tab (next to commits).

Task 1 Rename the fork: Settings  Repo name

Task 2 Change title in _config Can see green check mark in commits http://yourusername.github.io/projectname/

Task 3 (could be demo) “Working with Pages” (quick-start guide) https://mmistakes.github.io/minimal-mistakes/docs/pages/ Pre-supposes you know how to create a .md file with yaml. Less than ideal. (YAML is to markup data, like metadata. Superset of JSON) Let’s look at the code for their about page and copy the yaml (also: title, categories, tag) We can see the recommended layout default is “single” – so let’s leave it out of the yaml here Apply front matter defaults in _config Green checkmark? Does it load? What if we put in the URL directly? Update navigation.yml

• Uncomment the ‘about’
• Correct the URL

Task 4 (could be demo) Add image to new page. Wizard: https://pixabay.com/en/wizard-sorcerer-lego-action-figure-1662948/ Look at sample posts. Find “Markup: Image Alignment” Now find it in repo. We know it’s a Post. We can see made Jan 10, 2013. Copy text. Paste it into our page. Correct the .jpg name. Now create folder and upload image file into it.

• Need to have learned hashtags for commenting
• Need to be introduced to YAML

TLDR: I'm going to have folks follow along to apply a "supported" theme, update the config file, and edit the markdown to create text. This should be relatively quick, maybe ~20 minutes.

After that, I will demo installing an unsupported theme using the command line. I tried only using GitHub but it doesn't work; I cannot upload that many files using the web interface (it maxes out at 100). Folks will then have an opportunity to produce the same-ish outcome by forking the minimal mistakes repo. I'll show how to use the quick-start guide to apply the theme and create a new page. This can be the "next step" demo for GH Pages. I'll have to time myself to determine how long this demo will take. I've planned more tasks than will likely fit so I will play it by ear.

I've created a new github account for this purpose: https://github.com/alter-ego-gallingerj/