Writing Documentation
jekyll github

By Vanessa Sochat, Norman Heck

What

On this Page you can find instructions on how to write or edit this website. This is a Jekyll page living in the project’s github repository in the /docs subfolder. For more information on Github Pages see this documentation.

The theme of this documentation is built on this starter template. Everything has been modified to fit my needs. The original Apache License is included. For CSS Styling the latest Version of Tailwind is used. The Build Process of Tailwind is not running on the Github Server and needs to be deployed along with your Commit.

Up and Running

  • install Jekyll
  • clone the repository git clone https://github.com/festwertspeicher/jacques-loom
  • go to the docs folder cd /docs
  • install the packages npm install
  • serving the Jekyll page with livereload: - npm run jekyll:dev
  • watching for style changes in Tailwind files and creating the static and purged CSS file: - npm run css:watch

Support

If you need help, please don’t hesitate to open an issue.

Features

User Interaction

On thebottom of any page, you’ll notice links to edit the page, or open an issue. This ensures that any time you have a question or want to suggest or request a change, you can do so immediately and link directly to the section of interest. The sections on the page also have permalinks (¶) so you can link directly to them.

The entire site, including posts and documentation, is indexed and then available for search at the top or side of the page. Give it a try! The content is rendered into window data that is used by lunr.js to generate the search results. If you want to exclude any file from search, add this to its front end matter:

---
layout: null
excluded_in_search: true
---

The example above is for a javascript file in the assets folder that is used as a template, but should not be included in search.

If you have an external site with a search GET endpoint (meaning one that ends in ?q=<term>, then you can automatically link page tags to search this endpoint. For example, on an HPC site I’d want a tag like “mpi” to do a search on http://ask.cyberinfrastructure.org for mpi. See the tags section below for how to configure this.

Documentation

Documentation pages should be written in the docs folder of the repository, and you are allowed to use whatever level of nesting (subfolders) that works for you! It’s a Jekyll collection, which means that you can add other content (images, scripts) and it will be included for linking to. To create subfolders with files, you can simply create new markdon files. For example:

  • _docs/subfolder/example-page.md renders to http://localhost:4000/tw-jekyll/docs/subfolder/example-page/
  • _docs/subfolder.md renders to http://localhost:4000/tw-jekyll/docs/subfolder/

And the page you are reading now renders from _docs/getting-started.md

Organization

The url that will render is based on the path. For example, if we had the following structure:

docs/
  getting-started.md
  clusters/
     sherlock/
         getting-started.md

The first page (akin to the one you are reading) would render at it’s path, /docs/getting-started/.

Linking

From that page, we could provide the direct path in markdown to any subfolder to link to it, such as the second getting started page for sherlock:

[example](clusters/sherlock/getting-started.md)

Here is an example link to a relative path of a file (example-page.md) in the same directory, and from that page you can test linking to a subfolder. In the case of not having a subfolder, we could write the link out directly:

[example]({{ site.baseurl }}/docs/clusters/sherlock/getting-started.md)

or just put the relative path:

[Here](example-page)

or better, there is a shortand trick! We can use the provided “includes” template to do the same based on the path to create a link:

{% include doc.html name="Sherlock Cluster" path="clusters/sherlock/getting-started" %}

The path should be relative to the docs folder.

Pages

The pages folder uses the same page layout, but is not part of the docs collection. The two are provided to create a distinction between website pages (e.g., about, feed.xml) and documentation pages.

A Nested Page

This is an example of a page that doesn’t have a permalink defined, and is not included in the table of contents (_data/toc.yml). This means that it will render based on it’s path. Since it’s in docs/example-page.md, the url will be docs/example-page/.

Now let’s say we want to link to a subfolder, specifically with this setup:

docs/
  example-page.md  (-- we are here
  subfolder/
     example-page.md  (-- we want to link here

You can provide the relative path to the file, like subfolder/example-page.md and Jekyll will handle parsing it. For example:

And here is the same link, but generated with the include statement:

{% include doc.html name="here" path="subfolder/example-page" %}

Whether you place your page under “pages” or “docs,” for those pages that you want added to the navigation, you should add them to _data/toc.yml. If you’ve defined a permalink in the front end matter, you can use that (e.g., “About” below). If you haven’t and want to link to docs, the url is the path starting with the docs folder. Here is an example (currently the active example):

- title: Documentation
  url: docs
  links:
    - title: "Getting Started"
      url: "docs/getting-started"
    - title: "Extras"
      url: "docs/extras"
    - title: "About"
      url: "about"
    - title: "News"
      url: "news

If you want to add an external url for a parent or child, do this:

  - title: GitHub Repository
    external_url: https://www.github.com/vsoch/tw-jekyll

News Posts

It might be the case that your site or group has news items that would warrent sharing with the community, and should be available as a feed. For this reason, you can write traditional posts in the _posts folder that will parse into the site feed The bottom of the page links the user to a post archive, where posts are organized according to the year.

Buttons

The following buttons are available - you can match the class on the button to the examples below. All buttons include the basic .btn class.

<button class="btn btn-magnet">magnet</button>
<button class="btn btn-speed">speed</button>
<button class="btn btn-air">air</button>
<button class="btn btn-electronic">electronic</button>

Badges

For tags that appear on posts, you can edit badge_color in the _config.yaml to change the color. If not set, it defaults to the lovely purple of the main site. For news post items, it’s also nice to be able to tag it with something that indicates a status, such as “warning” or “alert.” For this reason, you can add badges to the front end matter of any post page, and they will render colored by a type, with the tag of your choice. For example, here is an example header for a post:

---
title:  "Two Thousand Nineteen"
date:   2019-06-28 18:52:21
categories: jekyll update
badges:
 - class: badge-speed
   name: deprecated
 - class: badge-air
   name: updated version
---

And to easily include a badge, just use the include:

{% include badge.html text="good-job" class="badge-speed" %}

To generate this:

good-job

Callout

A callout is a little box to draw emphasis to something:

Hey you, look right here!

That looks like this:

{% include callout.html text="Hey you, look right here!" %}

Or change the background color:

{% include callout.html text="Hey you! The sky is blue!" color="speed" %}
Hey you, look right here!

Quotes

Here is what a blockquote looks like. We could probably improve upon this with different colors, etc.

A famous person once said, “Hark! I do believe I’d like some cheese” – Famous Person

Development

Initially (on OS X), you will need to setup Brew which is a package manager for OS X and Git. To install Brew and Git, run the following commands:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install git

If you are on Debian/Ubuntu, then you can easily install git with apt-get

apt-get update && apt-get install -y git

Install Jekyll

You can also install Jekyll with brew.

$ brew install ruby
$ gem install jekyll
$ gem install bundler
$ bundle install

On Ubuntu I do a different method:

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
echo 'export PATH="$HOME/.rbenv/plugins/ruby-build/bin:$PATH"' >> ~/.bashrc
exec $SHELL
rbenv install 2.3.1
rbenv global 2.3.1
gem install bundler
rbenv rehash
ruby -v

# Rails
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
gem install rails -v 4.2.6
rbenv rehash

# Jekyll
gem install jekyll
gem install github-pages
gem install jekyll-sass-converter

rbenv rehash

Get the code

You should first fork the repository to your GitHub organization or username, and then clone it.

$ git clone https://github.com/<username>/tw-jekyll.git docs
$ cd docs

You can clone the repository right to where you want to host the docs:

$ git clone https://github.com/<username>/tw-jekyll.git docs
$ cd docs

Serve

Depending on how you installed jekyll:

jekyll serve
# or
bundle exec jekyll serve

Preview

We provide a CircleCI configuration recipe that you can use to preview your site on CircleCI before merging into master. You should follow the instructions to set up a project, and then in the project settings be sure to enable building forked build requests, and to cancel redundant builds. The preview will be built on CircleCI, and saved to static files for you to browse. The only change you will need is to edit the static files location to be the name of your respository, which is at te bottom of the .circleci/config.yml file:

      - store_artifacts:
          path: ~/repo/_site
          destination: tw-jekyll

In the above, the destination should coincide with your repository name. Remember that for most links, CircleCI won’t honor an index.html file in a subfolder (e.g., subfolder/index.html will not be served as subfolder/, so for example, you might need to turn this:

https://<circleci>/0/tw-jekyll/docs/getting-started/

into this:

https://<circleci>/0/tw-jekyll/docs/getting-started/index.html

Customization

config.yml

To edit configuration values, customize the _config.yml. There are a lot of small details that are included there that are not mentioned here! Please open an issue if you have questions.

Adding pages

To add pages, write them into the pages folder. You define urls based on the permalink attribute in your pages, and then add them to the navigation by adding to the content of _data/toc.yml.

Tags

If you include tags on a page, by default they will link to the tags page on the site. However, if you define a tag_search_endpoint url in your configuration file, by clicking the tag, the user will be taken to this page to search for it. As an example, we define the current search endpoint to be Ask Cyberinfrastructure, and page tags link to a search on it:

tag_search_endpoint: https://ask.cyberinfrastructure.org/search?q=

The tags appear at the top of the page, as they do on this page. The tags should be defined like this in the front end matter:

tags: 
 - jekyll
 - github

They are appended to the first h1 block, so generally your pages should have a header. If you comment out this variable, then each of your tags will link to it’s appropriate spot on the tags page linked above.

#tag_search_endpoint: https://ask.cyberinfrastructure.org/search?q=
tag_color: primary # danger, success, warning, primary, info, secondary

Edit