Jekyll

This site is hosted on GitHub Pages, powered by Jekyll. The .md files inside the repository are automatically discovered.

Front Matter

For Markdown files, Jekyll uses a Front Matter block for configurations.

In your .md file, use a header like this:

---
layout: docs
permalink: /HiTRACE/tutorial/bonus_2d/
root: /HiTRACE/
prev: /Biers/varna/
next: ../bonus_3d/

title: HiTRACE
description: "<u>Hi</u>gh-<u>T</u>hroughput <u>R</u>obust <u>A</u>nalysis for <u>C</u>apillary <u>E</u>lectrophoresis"
repo: ribokit/HiTRACE
author: Siqi Tian
---

Remember that all URL path (permalink, root, prev, next) are CASE SENSITIVE. Use spellings that match the actuall repository name!

System Fields:

Key	Value
`layout`	The layout template for the page. Use `default` for all pages; use `redirect` for redirecting a `permalink` to a new address (with a 301 page, see `redirect_to`).
`level`	The level for the page. This controls the navigation banner: `0` displays “Visit Lab” button; used for domain index page only (e.g. `https://ribokit.github.io`). `1` displays “View GitHub” and download package for repository; used for landing page of each package (e.g. `https://ribokit.github.io/RiboVis/`). `2` displays “up”, “prev”, “next” navigation buttons; used for tutorial series (e.g. `/HiTRACE/tutorial/step_0/`).
`permalink`	The URL that the page responds to. Always start and end with `/`.

Descriptive Fields:

Key	Value
`title`	The display title for the page. It will be displayed after the “RiboKit :” prefix; before the “\| RiboKit” suffix in browser title.
`description`	The subtitle for display. For acronyms, mark the initials with `<u>` for highlighting (on hover).
`repo`	The repository name in format of `organization/repository`. This powers the “View on GitHub” and “Download” buttons. If left out, those buttons are hidden.
`author`	The creator of the page. It will be displayed in the footer.
`ga_tracker`	Google Analytics tracker ID. This should only be set once globally as defaults.

Navigation Fields:

Key	Value
`root`	The root parent of the page. This will be used by the up arrow button.
`prev`	The previous page, used for tutorial series. This will be used by the left arrow button. Your relative or absolute path/URL is used as is.
`next`	The next page, used for tutorial series. This will be used by the right arrow button. Your relative or absolute path/URL is used as is.
`redirect_to`	New address to redirect a page. Only works when `layout` is `redirect`. Either relative or absolute path works.

Example of link redirection:

---
permalink: /primerize/
redirect_to:  https://daslab.github.io/Primerize/
---

Defaults

Within the same package, the title, description, repo, root, etc. are usually the same across all pages. In the _config.yml, you can define default values globally:

defaults:
  -
    scope:
      path: ""
    values:
      layout: "default"
      level: 1
      title: 
      author: "Siqi Tian"
      ga_tracker: UA-12345678-9

The settings are global when path: "" is empty.

Also, you can define defaults for a package:

defaults:
  -
    scope:
      path: "repos/ribovis"
    values:
      title: "RiboVis"
      description: "PyMol Commands by the Das Lab Style"
      repo: "ribokit/RiboVis"
      author: "Siqi Tian"
      root: "/RiboVis/"

Now for your individual .md files, you don’t need to repeat the default variables.

Submit to RiboKit

Mechanism

The GitHub Pages are hosted either at organization level via a organization/organization.github.io repository, or at each repository level as a gh-pages branch.

For Markdown tutorials, we centralize the documents into organization/organization.github.io repository; while Sphinx docs are using the other option.

This choice is due to complicated baseurl setup for gh-pages. The URL root (/) for each repository’s gh-pages is actually /package in the browser, thus making it difficult to refer to static resources (JS, CSS, images). Also updating the RiboKit theme is more cumbersome since you need to go over each repository. Since the tutorials are unlikely to change frequently, the shared organization/organization.github.io repository is OK.

Integration

The repository is organized that each package has its own folder. Use lower case with underscores (_) for folder names. The landing page should be named as index.md. Please follow this rule when contributing!

Double check the permalink, root, etc. paths with case sensitive.
Place images in a res/ folder inside your package folder. Images and other resources for a tutorial should stay with its package .md files. This helps the repository organization.
If necessary, update the organization/organization.github.io index page for links to your new writing.
Push the changes to GitHub. The website should be updated automatically (may be with some delay [< 30s]).