Submitty.org

This is the documentation website for Submitty, an open source course management, assignment submission, exam, and grading system.

To report issues for this repository, please file them under the Submitty/Submitty repository.

Local Development with Docker (Recommended)

If you have Docker installed, you do not need to install Ruby or Bundler locally.

Setup

1. Clone the repository:

   git clone https://github.com/Submitty/submitty.github.io.git
   cd submitty.github.io

2. Start the development container:

   docker compose up

   The first run will take a few minutes to install dependencies.

3. Visit http://localhost:4000 to view the site. Changes to files will automatically trigger a rebuild and refresh your browser.

4. To stop the development container, press Ctrl+C or run:

   docker compose down

Running the link checker

docker compose exec site bundle exec jekyll build
docker compose exec site bundle exec htmlproofer ./_site --assume-extension --empty-alt-ignore --disable_external

Alternatively, you can develop the site with Ruby and Bundler installed locally. See the instructions below for more information.

Local Development with Ruby

Prerequisites

To develop the site locally, you will need to get the following dependencies:

• Ruby
• Bundler (gem install bundler)

For Bundler, depending on your system, you may need to also install the Ruby development headers (e.g. ruby-dev). On Ubuntu/Debian, for example, this would be accomplished by doing sudo apt-get install ruby-dev.

Setup

1. Clone the repository on your local machine, e.g.,

   git clone https://github.com/Submitty/submitty.github.io.git
   

   • NOTE: We recommend placing the code in a directory/folder on your machine without spaces, because some developers have experienced errors with bundler when the full path contained spaces.

2. Use Bundler to install the dependencies. This can be accomplished by running:

   bundle install

   • NOTE: During the install, it may hang up when installing the dependency nokogiri. Don't worry: continue waiting. If it still is stalling here, press enter and it should continue.

   • NOTE: If an error is thrown during the installation process you may need to downgrade from 3.0 to use Ruby-2.7 and make sure this is indeed the version that the Bundler is using and not another one in a different directory.

Running the Site

• To view the site locally, and the results of any changes you make, you will want to use the jekyll commands through Bundler, namely the serve sub-command, as shown below:

  bundle exec jekyll serve

• NOTE: If you have an error running on the default port (4000), you can specify an alternate port, e.g.

  bundle exec jekyll serve --port 4001

• If you wish to build the site locally instead of running it, you can do:

  bundle exec jekyll build

  which will leave the results in a _site directory.

Running the link checker

GitHub Actions checks each pull request for broken links using the htmlproofer package. If you wish to run htmlproofer locally, cd into the submitty.github.io repository and run the command:

bundle exec htmlproofer ./_site --assume-extension --empty-alt-ignore --disable_external

Editing Content

The site's content is defined with markdown files under the docs/ folder, where then it's separated by a couple of high-level sections (student, instructor, sysadmin, developer). For any new page, a new entry must be added to the navigation manually (see below). The rendered markdown uses a variant of Github Flavored Markdown. For every page, it should have a front-matter block at the top of the file that has minimally:

---
title: Page Title
---

where this is used as the main header title on the page, as well as for the title of the page in the browser. You should then not include a # Page Title in the file, rather just start your content immediately after the front-matter block.

Navigation

Editing the links on the navigation is done by editing navtreedata.js. The structure of the file is that each level is a list of objects, where the object can have the following parts:

• name (required)
• link
• children

Where if link is omitted, then name will be used where it will be lowercased and spaced replaced with _. Children is then a list of objects of the above structure. Currently, the site only supports three levels of nesting (sub-sub-children).

Search

• Add excluded_in_search: true to any documentation page's front matter to exclude that page in the search results.

Forked from Edition

This repository was created via a fork of Edition, which is a product documentation theme for Jekyll created by CloudCannon, the Cloud CMS for Jekyll.

Ruby Version Troubleshooting

In February 2024:

• https://ritviknag.com/tech-tips/ruby-versioning-hell-with-jekyll-&-github-pages/