Skip to content
master
Switch branches/tags
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
log
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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!'

About

Website providing step-by-step instructions on participating in the SCIONLab network.

Topics

Resources

Releases

No releases published

Packages

No packages published