# Important Links: - A preview of the template: https://academicpages.github.io/ - The template repository: https://github.com/academicpages/academicpages.github.io


Introduction


Why use GitHub pages?

  • Free
  • Easily personalized
  • Only requires use of markdown instead of HTML or another complicated language
  • Version control
  • Can work together with people on a website


How does it work?

  • Uses Jekyll to convert markdown to HTML
  • Constructed using a gh-pages branch of GitHub repository



Creating the Git Repository

Make sure you…
1. Have a GitHub.com account.
2. Can access it from the command line


Templates

  • For this tutorial, we’re going to be using the Academic Pages template.
  • There are tons of templates out there to fit whatever kind of website you want to create. I recommend googling this outside of the workshop but following along with Academic Pages.


Local

  1. Clone the repository
  git clone https://github.com/academicpages/academicpages.github.io.git


  1. Change the name of the directory
  • Note that this will be your URL so make it something meaningful to you. You have two options:
    • User site:
      • URL: <username>.github.io
      • You need to name your repository both locally and on github <username>.github.io with your GitHub username in the place of <username>
    • Project Site:
      • URL: <username>.github.io/<repository>
      • <repository> will be the name of your local and remote repository
      • Github will know this is a website because you will be using the gh-pages branch
mv academicpages.github.io my_site


  1. Remove the .git file
  • These commands will ask you two question, answer yes to both of them.
  • This removes the .git history of this repository so you can create your own.
cd my_site
rm -r .git


  1. Initialize this git repository
git init


On GitHub

  1. Navigate to your account
  2. From the home page click new
  3. Fill in your repository name.
  • This should be the same as your folder locally. creating your repository
  1. Click create repository.
  2. It will bring you to the repository page
  • Copy your URL only, then go to your terminal and do the following commands. Be sure to change the <URL> to the one you copied.
git add .
git commit -m "first commit"
git branch -m master gh-pages
git remote add origin <url>
git push -u origin gh-pages


  1. Refresh your repository, it should be there! Now, we want to publish our website (or make sure that it published itself) Click settings in the upper right hand corner.

Your URL will be either https://USERNAME.github.io/REPONAME/ or https://USERNAME.github.io/ (if your repository name is your username)


Entirely online

This section is only for people who do not want a local copy of their repository, I don’t recommend doing it this way, but it’s an option if you must

  1. Go to the academic pages GitHub > click fork
  2. Change the name of your directory by going to Settings > Repository Name
  3. Change the branch to be gh-pages



Structure and Customization

File Name Description
CHANGELOG.md A log of all changes made by the template maintainer
CONTRIBUTING.md Information about how to contribute to the template
Gemfile Jekyll management
LICENSE Template use licensing
README.md This has instructions and information about the template
_config.dev.yml Config development override settings
_config.yml Basic information about your website
_data Information about the website
_drafts Draft blog posts
_includes Formatting HTML
_layouts Formatting HTML
_pages Each page’s .html file goes here
_portfolio The ‘Portfolio’ page
_posts Home to all blog posts
_publications The ‘Publications’ page
_sass CSS formatting
_talks The ‘Talks’ page
_teaching The ‘Teaching’ page
assets Non-markdown materials such as fonts
files Directory for any spare files
images Directory for all images used
markdown_generator Converting jupyter notebooks for talk map to markdown
package.json Information about original theme/licence
talkmap Generates a map of talk locations
talkmap.ipynb Generates a map of talk locations
talkmap.py Generates a map of talk locations

Bold indicates that we will edit these files in the workshop. The other files are for formatting. Edit with caution.


Editing _config.yml

Open the _config.yml document

  • Edit:
    • Title
    • Name
    • Description
    • URL
      • User site: <username>.github.io
      • Project site: <username>.github.io/<directory>
    • Repository: ‘/’
  • You can add any social media you’d like
    • Twitter
    • Instagram
  • Sidebar information
    • About me
    • We will change your avatar next
    • Bio
  • If there are fields in any of these sections you do not want to include you can either delete or comment them out.
  • Save this file!

If you edited this online, we now need to pull this locally. Navigate to your GitHub sites directory in terminal and type the following command:

git pull origin gh-pages


Adding a photo

Next we will add a photo for our sidebar. We will do this using the drag and drop method.

  • Go to images on the github website
  • Add file > upload files
  • COPY THE FILE NAME!
  • Return to the _config.yml file and paste into the avatar field.

Now we want to pull locally:

git pull origin gh-pages


Editing the authors

  • Go into the data directory
  • Click authors.yml and edit this information



Pages

The pages we will be making are:

  1. Publications
  2. Talks
  3. Teaching
  4. Portfolio
  5. Blog Posts
  6. CV

Remember your markdown that you learned on day two! Our layout also has a little markdown refresher page, you can view this by looking at the _pages/markdown.md file.


Publications

  • These are located in the _publications folder
  • There is a different file for each publication
  • If you click on one of these we can see there is a header at the top of each file
  • Put in your paper information.
  • This page is generated by the _pages/publications.html file
  • If you don’t want this page, you don’t need to delete all the entries. I’ll show you have to remove or add pages later on.
  • What if I delete all my files within the _publications folder? Can I get one back?
    • Yes! You can go to the original repository and view the code there. You can then just copy and paste the formatting. Everything you edit here will remain untouched there, so refer back at any time.


Talks

  • These located in the _talks folder.
  • Here, again, we have a different file for each talk or tutorial.
  • This page is generated by the _pages/talks.html file.


Teaching

  • These are located in the _teaching folder.
  • Editing this is very similar to the previous two sections, with a different file for each entry.
  • This page is generated by the _pages/teaching.html file.


Portfolio

  • You can use markdown and HTML files here, you just need to change the file extension.
  • Each portfolio item is, again, a different file.
  • This page is generated by the _pages/portfolio.html file.


Blog Posts

  • Your blog posts show up under the _posts directory.
  • Each post is a different file.
  • You can save draft posts in the _drafts directory
  • This page is generated by the _pages/year-archive.html file


CV

  • This does not have it’s own directory, as this is a single page it is in the _pages directory
  • This is automatically populated from the other sections. You can add or edit this as you’d like to change the top few sections (education, skills, …).


The Homepage

  • Edit _pages/about.md, this is your home page, you can write whatever you want here.
  • This is the first page displayed when people visit your website.


Adding and Removing Pages

  • Go into the data directory.
  • Click navigation.yml.
    • This is how we add links to our navigation.
    • All these directories point toward HTML files in the _pages directory.
    • Remove the markdown.md page.



Terminology

The GitHub glossary is a great resource for more vocabulary

  • repository: a directory for storing code.
  • fork: creates a copy of an existing repository to your account that is still connected to the original. If you think you’ve made productive changes to the code and want to change the original, you must submit a pull request and the author of the original repository must accept.
  • branch: creates a “parallel version of the repository” within the same repository. Branches can be merged at any time. You are in control of everything in this situation.
  • clone: creates a local copy of a remote repository. This makes the repository your own, it is no longer connected to the original repository and you cannot easily make changes to the original.



Git Summary

Everything in the following summary applies to the command line. For this lesson we will not work with accessing GitHub through R studio


Cloning

This copies a repository to your local directory structure. Automatically sets this as the origin directory.

git clone <url>

where <url> is the https url provided by GitHub


Pushing: Local > Remote

  1. Add your files to the staging area
git add


  1. Commit the changes in the staging area to the local repository history record
git commit -m "<description>"

where <description> is a note about your changes.


  1. Push the data to the remote repository
  • Note that this is the command for a regular repository.
git push origin master
  • For a github sites repository use the following instead of the above code.
git push origin gh-sites


Pulling: Remote > Local

  • Note that this is the command for a regular repository.
git pull origin master
  • For a github sites repository use the following instead of the above code.
git pull origin gh-pages