SCION tutorials page

The website is deployed at docs.scionlab.org/ using GitHub Pages.

About

SCION tutorial pages are written in markdown and they are placed in the content directory (with one exception: the home page is in ./index.md).

The HTML website is generated using Jekyll with the just-the-docs theme.

Building pages

The webpage is rebuilt automatically when you push to GitHub. If you don't want to see the preview before pushing, you can stop reading now. (Using a Markdown-capable editor, such as the online editor online, might work well for this.)

If you want to preview the docs locally, you need to install the github-pages and other supporting gems (installs Jekyll in the same way as it is installed on GitHub pages):

make install

(You need a working Ruby+bundler install first, install those from your OS's packages. You might have to install the 2.5 version specifically.)

In order to generate the website, run:

make build

The newly generated website will be placed in the _site directory.

During the development phase, it is possible to run a local webserver and automatically refresh the website content. To do this, run:

make serve

Adding a new page

Create a .md file inside content (or an appropriate subdirectory, if it will have sub-pages). This file must have a YAML front matter, which determines the site navigation structure.

Top-level page

Create content/some-topic/index.md (or just content/some-topic.md) with content like:

---
title: Some Topic
nav_order: 47
has_children: true  # omit if you don't want second-level pages
---

This is my content.

Second level page / child page

Create content/some-topic/some-subtopic.md with content like:

---
title: Some Subtopic
parent: Some Topic
nav_order: 42
---

This is my content.

See https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/ for more info about the site navigation.

Extras

TODO somebody should upstream these one day.

Alert/Tip/Note box

{% include alert type="Warning" title="DANGER!!1!" content="
I am _very_ **dangerous**!
" %}

Theme customization

We use the just-the-docs theme as a "remote theme", which means that the theme source is not included in this repository. The theme can be customized by defining a new color scheme (_sass/color_schemes/scionlab.scss) or by adding custom CSS in _sass/custom/custom.scss: see just-the-docs customization docs).

Check HTML and Links

You can always look for broken links and correct HTML in the tutorials by running:

make serve
make check # in a second terminal

Prior to merge to master it is always nice to check against our own repository. For that you need to enable Github Pages in your clone of scion-tutorials, and remembering that Github Pages are available only for the master branch, your commits would have to be pushed to your master. E.g.:

git push myremotename HEAD:master
sleep 30
wget --spider -r -nd -nv -l 3 -w 0 -o - https://mygithubusername.github.io/scion-tutorials/ | grep -B1 'broken link!'