UBC Library Research Commons: workshop template

Start with the instructions below to setup a Research Commons workshop repository and website. For more customization and configuration options see Just the Docs documentation.

Set up the RC workshop site

1 Go to https://github.com/ubc-library-rc/template and click the green “Use this template” button. Select “ubc-library-rc” as the owner, add a name, ensure the repository is set to “Public”, then click “Create repository from template”

2 The _config.yml file in your new repository contains information about the site:

title: Title of workshop
remote_theme: ubc-library-rc/rc-theme
color_scheme: rc
github_repo_url: "https://github.com/ubc-library-rc/REPOSITORY-NAME/" 

# license information for workshop content
license_name: "Creative Commons Attribution 4.0 International License"
license_url: "http://creativecommons.org/licenses/by/4.0/"
license_image_url: "https://i.creativecommons.org/l/by/4.0/88x31.png"

# required for building jekyll site locally
plugins:
  - jekyll-remote-theme
  - jekyll-seo-tag

Replace the following:

• title with your workshop title
• github_repo_url with your GitHub repository URL (replace only the “REPOSITORY-NAME” part)
• license_url, license_name, and license_image_url with the license you will apply to your content

If you’re not sure what license to choose the Creative Commons Attribution 4.0 International License is a good default for Research Commons OERs. The license_image_url is optional (maximum 150px wide).

3 In the new repository, turn on GitHub Pages:

• Go to Settings
• Scroll down to the GitHub Pages section
• Under Source, select Branch: main

If you don’t see these options under GitHub Pages ensure the repository visibility is public (see the Change repository visibility setting)

After completing these steps the workshop site should be available at https://ubc-library-rc.github.io/REPOSITORY-NAME/. It may take a few minutes for GitHub to generate the site.

4 Update the README.md file with your workshop title and link.

Add/edit content pages

The template includes several files that render as pages in the workshop site:

By default the introduction.md file is in the content folder, which also contains directories for images used in the site.

Workshop content pages are written in Markdown (see Markdown guide). Create an .md file for each page you would like to add to the site. Include the following YAML header at the start of each .md file.

---
layout: default
title: Title of page
nav_order: 1
---

The nav_order line establishes where the page will appear in the navigation menu (higher numbers appear lower in the list).

Add child pages

Top-level pages on the site (parents) can also have sub-pages (children). Child pages appear in drop-down menus below their parent. The relationship between parent and child pages is defined in the YAML headers of both pages.

Add this to the header of the parent page:

has_children: true

Add this to the header of the child page:

parent: Title of parent page

TOC on parent pages

By default, all pages with children have a Table of Contents that lists the child pages after the parent page’s content. To disable, set has_toc: false on the parent page:

has_children: true
has_toc: false

Exclude a page from navigation menu

By default the title of each .md file will appear in the left navigation menu. To exclude a page add the following to its YAML header

nav_exclude: true

Selected text formatting options

Below are some formatting options that may be useful in RC worskhop sites. For more configuration options see Just the Docs documentation.

Callouts

Use this syntax…

Wash your hands frequently
{: .note}

… to include a note that will look like this on the workshop website:

Wash your hands frequently

Don't step on the snails!
{: .warn}

Don’t step on the snails!

Basic slug identification; comfortable in the woods.
{: .prereq}

Basic slug identification; comfortable in the woods.

Step-by-step instructions

Step 1
{: .label .label-step}
Do this thing
{: .step}

Step 2
{: .label .label-step}
Do this other thing
{: .step}

Step 1

Do this thing

Step 2

Do this other thing

Terminal input/output

Sometimes it’s helpful to distinguish between what a workshop participant should input into the terminal or command line, and what they should expect as output. This code for an input…

Input
{: .label .label-green }
```sh
$ git status
```

… will appear like this in the workshop website:

Input

$ git status

Similarly, this code shows the output from a command:

Output
{: .label .label-yellow }
```sh
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working tree clean
```

Output

On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working tree clean

Code block syntax highlighting

Add syntax highlighting to code blocks by specifying the language after the three backticks at the beginning of a block. The example below is for markdown (md). Other syntax options include html, xml, js, py, sql, sh, yaml, and many more.

```md
Code block with [markdown](https://markdownguide.org) syntax highlighting.
```

Code block with [markdown](https://markdownguide.org) syntax highlighting.

Circled numbers

This synax…

*1*{: .circle .circle-blue} Number in normal text

…will look like this:

1 Number in normal text

You can also use this in headers, lists and other markdown suported elements, e.g.,

* *1*{: .circle .circle-blue} `.circle-blue`
* *2*{: .circle .circle-red} `.circle-red`
* *3*{: .circle .circle-yellow} `.circle-yellow`
* *4*{: .circle .circle-green} `.circle-green`
* *5*{: .circle .circle-purple} `.circle-purple`

## *2*{: .circle .circle-red} Number in h2

### *10*{: .circle .circle-yellow} Number in h3

…will look like this:

• 1 .circle-blue
• 2 .circle-red
• 3 .circle-yellow
• 4 .circle-green
• 5 .circle-purple

2 Number in h2

10 Number in h3

Dropdowns

To create hidden content in a dropdown use this:

<details>
<summary>This is the dropdown title</summary>
<br>
This is the hidden dropdown content.
</details>

If you want it open by default:

<details ope
<summary>This is the dropdown title</summary>
<br>
This is the dropdown content that you can hide if you want to.
</details>

Table of contents

See In-page navigation with Table of Contents for options to add a TOC within a page (like at the top of this page).