Contributing to CoNCH Lab Wiki

Get started

The lab wiki is powered by GitHub Pages using Jekyll. The website is deployed from the gh-pages branch, so for changing the content, you’ll need to commit your changes to this branch. However, you should create a new branch for the changes you want make and when you want to publish them, create a pull request to the gh-pages branch.

  1. To get your hands on editing, start by cloning the repository:

     git clone https://github.com/CoNCHLab-Github/conchlab-github.github.io.git

  2. Then, checkout the gh-pages branch:

     git checkout gh-pages

  3. Now, you’ll need to install and run Jekyll locally to be able to preview the website. Follow this guide for the instructions: Testing your GitHub Pages site locally with Jekyll

  4. From the gh-pages branch, create and switch to a new branch for the changes you intend to make:

     git switch -c <branch-name>

  5. Refer to the other sections on this page to learn how the website works and how you can edit it or add your own content.

  6. Create a pull request to the remote gh-pages branch.

Structure of the website

The repository looks like the following:

.
├── 404.html
├── assets
│   ├── css
│   └── img
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── _guides
│   ├── backup
│   ├── backup.md
│   └── ...
├── _includes
│   └── toc.html
├── index.md
├── journal_club.csv
├── journal_club.html
├── _layouts
│   ├── default.html
│   ├── home.html
│   ├── post.html
│   └── wiki.html
├── _posts
├── _site
└── _tutorials
    ├── computecanada.md
    ├── git.md
    └── mTRF.md

Files:

  • 404.html: the “not found” page for when the url cannot be resolved.
  • _config.yml: contains the website configurations like the description, logo, and etc.
  • Gemfile and Gemfile.lock: files related to managing Ruby gems, which are packages of Ruby applications or libraries (don’t edit these files).
  • index.md: content for the index page (you’ll find this empty except for declaring the layout since the content is automatically generated. More details are discussed in Index/Home page section).
  • journal_club.csv: stores the data about the journal club sessions (the discussed articles) in a comma-separated format.
  • journal_club.html: html file for the journal club page, uses the journal_club.csv to create the schedule table.

Directories:

  • assest: a directory for the assests like .css style files in the css subfolder and images (e.g. lab logo) in the img subfolder.
  • _guides: a directory for markdown files, each .md file is a page automatically listed under guides on the index page.
  • _includes: a directory storing tools included in the website, e.g. toc.html which is used to create auto generated table of contents.
  • _layouts: a directory storing all layouts used in the website. Layouts are used to convert the markdown files to html pages.
  • _posts: a directory for storing the posts.
  • _site: the directory storing site pages and assets. Files and subdirectories of _site directory are auto generated by Jekyll after transforming the markdown content to html pages using layouts, do NOT edit this directory directly.
  • _tutorials: a directory for markdown files, each .md file is a page automatically listed under tutorials on the index page.

Index/Home page

The index.md files triggers the generation of the index.html page by Jekyll. The markdown only declares the layout like the following and everything happens in the home.html layout in _layouts.

---
layout: home
---

The home layout reads the markdown files inside _guides and _tutorials and list them by their title defined in the markdown files under the corresponding category. You edit the layout to change the categories or accomodate other categories.

Layouts

Layout html files are used by Jekyll to transform a corresponding markdown file to a html file that is then included in the website. In this project layouts use Bootstrap framework for responsive pages, tables, etc.

Journal Club page

Edit an existing page

Make sure you create and switch to a new branch (with a meaningful name) for the modifications you plan, before starting your edits!

To edit a page you need to edit the corresponding markdown file. For example, if you want to edit this page (with the address https://conchlab-github.github.io/guides/contribution.html, indicated in your browsers address bar) you need to edit the contribution.md located at _guides directory. The same pattern of association holds for other pages.

If you are not familiar with markdown language you may find the Markdown Guide helpful to get started.

Adding a new page

Make sure you create and switch to a new branch (with a meaningful name) for the modifications you plan, before starting your edits!

Create a new markdown file with a meaningful name accordingn to the content of the page you are creating. Depending on whether you want your page to be automatically listed under a predefined category (e.g., Tutorials or Guides) or not, you would want to place the markdown file under the associated directory. If your new page does not fall under any of the categories make sure it is proparly linked in other pages and is reachable. Your markdown file should start like the following:

---
layout: wiki
title: your new page title
---

The content of your page **in markdown syntax**.

You can specify any valid layout (a layout that exist under _layouts directory) instead of wiki. You can define any other variable that is used by your layout other than the page title.