How this site is generated

This website is generated using the Jekyll static site generator with the Just the Docs theme.

Source Location

This site is developed and built from {site.local_path}. It is a Git repository that syncs to <{site.git_url}>.

Deploying changes

After making changes in the source location, log in to smaug and run the deploy.sh script. This will use a Ruby installation present on the /scratch drive of smaug and the bundle command to rebuild the website and copy its contents to <{site.url}{site.baseurl}>.

Reset environment

If the source location is destroyed, it may be recreated by doing the following:

git clone {site.git_url}

Installing Ruby, Bundle, Jekyll

  • Jekyll can be run with Ruby 2.5.0 or higher.

  • I use rbenv installed in my home folder to run Ruby 3.2.2, but this shouldn’t be necessary. (I had to install some dependencies to build Ruby 3.2.2 with rbenv , like libyaml-devel)
  • RubyGems is also required (and comes with any Ruby installation from rbenv).

  • The only thing you have to install with gem is Bundler, which provides a way to set up an isolated environment of Ruby packages.

    gem install bundler

  • Then to install everything needed to build the site, from the source directory, just run

    bundle install

    This will create the vendor and bin folders with jekyll and all the required dependencies downloaded and ready to run.

  • To add other software (e.g. Jekyll plugins) to the bundle, either use bundle add <GEM_NAME>, or manually add a gem dependency line to Gemfile and then run bundle update.

Development

Admin/User

  • There are actually two separate sites, the admin and user sites for storing their respective documention. This was done due to Just the Docs only having three levels of navigation depth and fairly different content for the admin and users. This is done in such a way that most of the configuration files for the two sites are shared. Specifically:
    • user/.bundle/config is a symlink to admin/.bundle/config. That file sets the base locations for the vendor and bin directories to the root of the repository so both sites use the same Ruby stuff.
    • user/Gemfile and user/Gemfile.lock are both symlinks to files of the same name under admin so both sites have the same gems installed (which is necessary anyway with the shared vendor and bin dirs)
    • user/index.md is a symlink to admin/index.md and has links to both sites, so it’s easy to get from one to the other.
    • user/_sass/custom/custom.scss is a symlink to the same path under admin to keep styling consistent.
    • index.html redirects to user/admin.html
  • The page content for each subsite is located in the docs folder, and consists of various Markdown files.
    • To add a new page, create a markdown file somewhere in the docs folder.

    • At the top of every page should be a section of YAML front matter that includes, at a minimum, a title attribute, and typically a parent attribute as well. For example, the front matter for the page at docs/admin/logs/2022_system_setup_01.md is:

      ---
title: CIL Admin Logs - part 1
parent: CIL Admin Logs
---

      The parent attribute is the title of the page to nest this page under in the navigation. In addition, a page may have has_children: True to indicate that it may have child pages in the navigation. A page at the tertiary level also requires the grand_parent attribute. See the Just the Docs documentation for more info.

    • To add a table of the contents to the page, include the following markdown at the top of the page:

      - TOC
{:toc}

      To make the TOC hideable, use the following:

      <details open markdown="block">
<summary>
  Table of contents
</summary>
{: .text-delta }
- TOC
{:toc}
</details>
      • This GitHub gist has good info on how to use the <details> and <summary> HTML tags to create collapsible sections in Markdown.
    • To number the headings, add numbered-headings: True to the front matter. Note that there is a bug that causes Jekyll to add the numbers to the heading’s HTML id attribute, so to link to a heading without needing to predetermine the heading number you have to manually add an anchor to the heading, as shown in this jekyll-numbered-heading issue.

    • To link to an attachment or include an image, put the file in the ./assets/attach or .assets/images dir as appropriate, then in the markdown file use the Liquid syntax or as the base dir for the file. For example, the image PuTYY1.png is included in the docs/user/ssh/index.md file with the following syntax:

      ![New Putty Session (1)](/PuTTY1.png "New PuTTY Session (1)")
    • These directories and other Jekyll and Just-the-Docs configuration parameters are defined in the _config.yml file.

Deployment

The deploy.sh script in the source repository does the following for each subsite:

  • Converts spreadsheets to HTML
  • Checks that changes have been committed to the repo
  • Adds a commit string to the home page
  • Runs bundle exec jekyll build to generate the website in the _site dir
  • Copies the site to the web directory on the web server (balulu).

The directories and files in the web server’s /var/www tree are owned by the admin user (pittmara at the time of this writing) but with 644 permissions on all files and 755 permissions on all dirs. This ownership should be changed if someone else is managing the website.

To test website changes before commiting them to the git repo, either answer y at the prompt or run deploy.sh -y.