This lesson is still being designed and assembled (Pre-Alpha version)

Workshop Title: Customizing Your Workshop's Website

Table of Content

Introduction

The following instructions walk through the set up steps to create a new workshop for the Digital Scholarship Hub using GitHub Pages. This workshop template is most appropriate for workshops teaching coding as the template contains styling elements for different coding languages including R, Python, BASH, SQL etc.

Necessary Tools

GitHub Account

You need to have a GitHub account. Create a GitHub account at github.com. Send an email to lib-sys@uic.edu to be added to the uic-library organization and the hub2 team.

Git installation on local computer

There are several editing options explained further in the How to edit GitHub Pages section. Mac computers will already have git installed by default. Windows users should install Git for Windows if they want to work on their local computer.

Basics of GitHub Pages

It’s recommended to review the following for working in GitHub Pages:

GitHub Pages Workshop Website Setup

Using the workshop template

  1. Log in to GitHub. You must be logged in for the remaining steps to work.

  2. On this page (https://github.com/uic-library/workshop-template), click on the green “Use this template” button (top right). Please do not fork this repository directly on GitHub. use template

  3. Choose UIC Libray as the owner for the repository UNLESS you are just practicing or practicing with the repository (Only Admins can delete repository’s in the UIC Library’s organization) repository owner

  4. Always edit or merge edits into the gh-pages branch. This is the branch that will be rendered as a live website

Repository Configurations

GitHub Pages sites are formatted as https://GITHUB_USERNAME.github.io/REPOSITORY_NAME. For example, if the URL for your repository is https://github.com/uic-library/Introduction-Digital-Scholarship, the URL for its website will be http://uic-library.github.io/Introduction-Digital-Scholarship.

url and repository information

Sharing & Visibility for Hub team

Go to Settings > Collaborators and teams

sharing & collaboration

Make the Website Public

1) Make sure url is set according to above instructions 2) Go into settings > Pages > and choose “Public”

public GitHub Pages

*until you set the url public, the website will render at random url, such as: private repository

*Error - you may get a 404 error when you go to the site after setting it as public. That is because the browser cache is not up to date, but this will resolve within a few days. You may also resolve the issue temporarily by opening the page in an incognito window or by forcing a reset of your browser cache.

Files to edit to build workshop website

To complete the set up of your workshop you will need to edit the follow files or add files to the folders highlighted below:

Files to edit

How to edit GitHub Pages

There are two ways of customizing your website. You can either:

Updating the files on GitHub in your web browser

  1. Go into your newly-created repository, ensure you are on the gh-pages branch by clicking on the branch under the drop down in the menu bar (see the note below):

    screenshot of this repository's GitHub page showing the "Branch" dropdown menu expanded with the "gh-pages" branch selected

  2. Use the pencil icon to go into editing mode and make your edits: screenshot showing the edit icon in GitHub Pages

*Note working on your workshop online is prone to losing edits due to internet outages. Either save very frequently, or edit locally.

Working locally

Command Line

If you are already familiar with Git, you can clone the repository to your desktop, edit your workshop locally, and push your changes back to the repository.

git clone https://github.com/uic-library/workshop-repo-name/

In order to view your changes once you are done editing, if you have bundler installed (see the installation instructions, you can preview your site locally with:

make serve

for Macs or

bundle exec jekyll serve

for Windows

and go to http://localhost:4000 to preview your site.

If there are any issues with the edits you made, you will get an error message from jekyll. See common jekyll error messages here to help with troubleshooting.

Once you are satisfied with the edits to your site, commit and push the changes to your repository. A few minutes later, you can go to the GitHub Pages URL for your workshop site and view it.

GitHub Desktop App

Alternatively, you can download and install the GitHub Desktop application, though you won’t be able to preview edits as you would with the command line.

* Highly recommend becoming comfortable using Git in command line at least for adding, commiting, previewing, and pushing changes. It can take a long time for a push to load on GitHub oneline and to be able to see the change to the website.

Workshop Website Detailed Instructions

Configuration File _config.yml

You should edit the _config.yml configuration file in the root directory of your workshop to configure some site-wide variables and make the site function correctly:

You should not need to modify any of the other variable values in _config.yml.

config.yml

Home Page (index.md)

Your workshop’s home page lives in index.md, which must contain the following information (edited in markdown):

*Note workshop content will display automatically from the titles of the workshop pages, estimated times, and objectives.

Setup Page (setup.md)

*Adding and removing installation instructions

If you need to add tools: If you need to add installation instructions for other tools, you can use the {% include %} statements for the tools located in _includes/install_instructions/ folder. in the format:

{% include install_instructions/<install-file-name.html>%}

If you need to add installation instructions for tools that do not currently have installation instructions, you will need to write your own in html in the install_instructions folder. You can use installation instructions for other tools located in the _includes/install_instructions/ folder as examples.

If you need to remove tools:

If you need to remove any of the instructions for the default set of tools, you can delete lines that include these instructions in the setup.md file.

for example, delete:

{% include install_instructions/r.html%}

Workshop Content Pages _episodes/

Images _fig/

*When linking images, usually the relative link you need is “../fig/image-to-link.png” *When linking images (and other files), the links are file sensitive. So if you link “../fig/01-intro-picture.PNG” the file extension in the image folder must be .PNG not .png.

Files files/

Additional Resources more-resources.md

*Should be edited with markdown

References reference.md

*Before re-using workshop materials, make sure they are licensed for re-use.

Troubleshooting

Transferring workshop to UIC Library - admin and maintainer permissions lost.

There have been issues several times when transferring a workshop from a personal GitHub account (for initial editing) to the uic-library that everyone loses administrative rights to the repository (which means the settings are totally unaccesible) If that happens, follow these steps:

  1. Create a new repository in uic-library organization

  2. Clone the original repository (the one with issues) locally: a. 
     git clone <insert original repository url here>

 cd <repository folder>
  3. Name upstream repository (in the new repository) 
     git remote rename origin upstream
  4. Set origin as the original repository 
     git remote add origin <original repository url>
  5. Push content from original repository to the new repository on GitHub 
     git push origin gh-pages

For more details see this stack overflow thread on the topic.

Deleting a repository

Only Library Systems has rights to delete repositories. Contact lib-sys@uic.edu to request deletion.

Website build errors

If you see a red check next to a commit on GitHub, that means the website was not built or updated due to an error. When editing locally, jekyll will show the issue if you use the local preview option (see How to edit GitHub Pages > Working locally). Otherwise, if you are editing on GitHub, you can go to Actions and see the errors there.

Common issues that cause build errors:

Workshop Template Markdown styles

The Digital Scholarship Hub workshop template was developed from the carpentries workshop template. There are extra styling and formatting options to better display code and for challenges, tips etc.

Formatting Code

Inline code fragments are formatted using back-quotes. Longer code blocks are formatted by opening and closing the block with ~~~ (three tildes), with a class specifier after the block:

~~~
for thing in collection:
    do_something
~~~
{: .source}

which is rendered as:

for thing in collection:
    do_something

The class specified at the bottom using an opening curly brace and colon, the class identifier with a leading dot, and a closing curly brace. The template provides three styles for code blocks:

.source: program source.

.output: program output.

.error: error messages.

Syntax Highlighting

The following styles like .source, but include syntax highlighting for the specified language. Please use them where possible to indicate the type of source being displayed, and to make code easier to read.

.language-bash: Bash shell commands:

echo "Hello World"

.language-html: HTML source:

<html>
<body>
<em>Hello World</em>
</body>
</html>

.language-make: Makefiles:

all:
    g++ main.cpp hello.cpp -o hello

.language-matlab: MATLAB source:

disp('Hello, world!')

.language-python: Python source:

print("Hello World")

.language-r: R source:

cat("Hello World")

.language-sql: SQL source:

CREATE PROCEDURE HelloWorld AS
PRINT 'Hello, world!'
RETURN (0)

Highlighting for other languages

You may use other language-* classes to activate syntax highlighting for other languages. For example,

~~~
title: "YAML Highlighting Example"
description: "This is an example of syntax highlighting for YAML."
array_values:
    - value_1
    - value_2
~~~
{: .language-yaml }

will produce this:

title: "YAML Highlighting Example"
description: "This is an example of syntax highlighting for YAML."
array_values:
    - value_1
    - value_2

Note that using .language-* classes other than .language-bash .language-html, .language-make, .language-matlab, .language-python, .language-r, or .language-sql will currently cause one of the tests in the lesson template’s make lesson-check to fail for your lesson, but will not prevent lesson pages from building and rendering correctly.

Special Blockquotes

We use blockquotes to group headings and text rather than wrapping them in div elements. in order to avoid confusing [Jekyll][jekyll]’s parser (which sometimes has trouble with Markdown inside HTML). Each special blockquote must begin with a level-2 header, but may contain anything after that. For example, a callout is formatted like this:

> ## Callout Title
>
> text
> text
> text
>
> ~~~
> code
> ~~~
> {: .source}
{: .callout}

(Note the empty lines within the blockquote after the title and before the code block.) This is rendered as:

Callout Title

text text text

code

The lesson template defines styles for the following special blockquotes:

.callout

An aside or other comment.

.challenge

An exercise.

.checklist

Checklists.

.discussion

Discussion questions.

.keypoints

Key points of an episode.

.objectives

Episode objectives.

.prereq

Prerequisites.

.solution

Exercise solution.

.testimonial

A laudatory quote from a user.

Note that .challenge and .discussion have the same color but different icons. Note also that one other class, .quotation, is used to mark actual quotations (the original purpose of the blockquote element). This does not add any styling, but is used to prevent the checking tools from complaining about a missing class.

Most authors will only use .callout, .challenge, and .prereq, as the others are automatically generated by the template. Note that .prereq is meant for describing things that learners should know before starting this lesson; setup instructions do not have a particular style, but are instead put on the setup.md page.

Note also that solutions are nested inside exercises as shown below:

> ## Challenge Title
>
> This is the body of the challenge.
>
> ~~~
> it may include some code
> ~~~
> {: .source}
>
> > ## Solution
> >
> > This is the body of the solution.
> >
> > ~~~
> > it may also include some code
> > ~~~
> > {: .output}
> {: .solution}
{: .challenge}

The double indentation is annoying to edit, but the alternatives we considered and discarded are worse:

  1. Use HTML <div> elements for the challenges. Most people dislike mixing HTML and Markdown, and experience shows that it’s all too easy to confuse Jekyll’s Markdown parser.

  2. Put solutions immediately after challenges rather than inside them. This is simpler to edit, but clutters up the page and makes it harder for tools to tell which solutions belong to which exercises.

Applying a Shadow to Images

By default, images in the lesson are displayed without borders or shadows. In some circumstances, it may be desirable to make images stand out from the background of the page, for example, when using screenshots that include text on white background. You can add a drop shadow effect to images by applying the image-with-shadow class to them:

![image alt text](path/to/image/source.svg){: .image-with-shadow }

Adding Formatted Equations

The template supports rendering of equations via KaTeX. This option must be activated by adding math: true to the _config.yml file or YAML front matter of the Markdown file where you wish to use it.

Mathematical expressions can then be added to the page content using the LaTeX syntax.

Expressions can be written inline:

Inline expressions can be added between `$` symbols, e.g. $E = Mc^2$.

with the result:

Inline expressions can be added between $ symbols, e.g. $E = mc^2$.

Or as a block across multiple lines:

$$
    \lim_{x \rightarrow 0}
    \frac{
        \sin x
    } {
        x
    }
    = 1
$$

with the result:

\[\lim_{x \rightarrow 0} \frac{ \sin x } { x } = 1\]

The example above was taken from the chapter Typesetting Mathematical Formulae, in The Not So Short Introduction to LaTeX. The Mathematics chapter of the LaTeX WikiBook is a good reference guide for those wishing to add equations and mathematical expressions to their lessons.