CS135 Web Site Repo

Never, ever edit the web site directly. The CS135 web site is now generated by a static site generator Hugo. When it is regenerated, whatever edits you make directly will be overwritten. Read on to learn more.

Overview

A static site generator takes input files that follow specified conventions and generates all the HTML required for the site. Advantages of a static site generator include a consistent look and feel, as well as leveraging work done by others.

The vast majority of the site is written in Markdown, a restricted but much easier to read and write language that maps to HTML. One can also use HTML directly, but if you're feeling the need to do that you should definitely check with the ISC or course coordinator first. Using raw HTML should be rare.

The web site is now under version control. This allows multiple people to work on it (hopefully) without conflict. It allows people to more easily check their work (see below) before making it live. It also allows us to know who's been doing the changes.

Directory Layout

  • archetypes: The starting point for new pages. Do not change without direction from permanent staff.
  • assets: Custom assets for the site (e.g. CSS). Do not change without direction from permanent staff.
  • content: The content of the web site. This is the main place where things will change. Note that the directory structure corresponds directly to the table of contents structure. Pages here are generally written in Markdown, as mentioned above.
  • data: Use currently unknown. Probably internal use by Hugo.
  • layouts: Various kinds of templates that are used by Hugo to render the site. Do not change except for strings representing constants for the current term (e.g. link to current MarkUs instance).
  • public: Where Hugo puts the rendered site. Changing anything here will be quickly overwritten.
  • resources: Use currently unknown. Probably internal use by Hugo.
  • static: Site-wide resources that are copied directly into public_html. Stuff like images and cgi-scripts. Note that images used for a specific page (e.g. staff photos) can be bundled in the content directory.
  • themes: The theme that is applied to the content when the site is generated. Do not change.

Prepping for a new term

Stuff to remove. Remember to use the SVN commands, since this is under version control.

  • Remove content/assess/post-mortem/*.pdf
  • Remove content/assign/a[01][0-9]/*
  • Remove content/cc/instructor_materials/*
  • Remove content/cc/tutorials/*
Pages to update:
  • Remove the errors from content/cc/_index.md (hopefully they've been corrected!)
  • Update content/help/personnel.md
  • Update the calendar at content/_index.md Note that it is generated from the calendar in the repo.
  • Update the exam info on content/assess/exams.md
  • Update content/assign/_index.md. Ideally, it will have all the assignments and due dates, but with the fourth parameter set to "false" until the assignment has actually been released.
  • Update the Racket version on content/assign/dr_racket.md
Other:
  • Replace the course slides in content/cc/slides
  • Remove the old solutions on the course web site
    • ~/protectPDF/*.pdf
    • ~/protectPDF/a[0-9][0-9]_soln
    • Leave the sample finals and midterms.
    • Edit ~/protectPDF/config.php to reflect what you did
Commit the changes to the repo. Make sure they got properly deployed to the live site.

Stuff below is out-of-date. To be updated soon by bwbecker

How to update the web site

One-time setup:

  1. Clone the repo to your own account. Subsequent steps go most smoothly if you use the ssh version: git clone ist-git@git.uwaterloo.ca:CS_135/web.git
  2. Ensure that Hugo is installed
    1. Do a which hugo to see if it's installed
    2. If not, go to the Hugo site and install it.
      If you're on a Mac and already have homebrew installed, it's as simple as brew install hugo at the command line. If you don't have homebrew installed, you'll need to run /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" at a terminal first.
    3. If you're not on a Mac, you're on your own...
  3. [Optional, but highly recommended:] Install a reasonable interface to git.
    SourceTree is recommended. You unfortunately have to create a (free) account at BitBucket to use it, but it's worth it to avoid the git command line.
Do the update:
  1. Do a fetch in the repo to make sure you have the latest version of the web site.
  2. Find the right page, almost certainly in the contents directory mentioned above. Pay attention structure in the site's table of contents to guide you to the location. Note that some files are called _index.md; in that case the name of the enclosing directory is helpful.
  3. Edit the file. Pay attention to existing conventions.
  4. At the command line in the web site's home directory (so that ls lists the directories listed above), run hugo serve. Then point your browser at localhost:1313. You should see a local copy of the site to check your work. Changes to scripts probably can't be checked this way; but you probably won't be making changes to scripts smile
  5. When all is good, commit your changes and push them to the master branch of the remote repo. A script will automatically update the web site.

Implementation Details

  • The repo at git.uwaterloo.ca has a "hook" for when "push events". Look under "Settings/Integrations". When there is a push to the repo, git.uwaterloo.ca sends an HTTP push to a specific URL, https://student.cs.uwaterloo.ca/~cs135i/cgi-bin/update_web.py. Notice the "i" in "cs135i".
  • updated_web.py is a pretty simple python script that does some security checks, verifies that it was a push to the master branch (ignoring others). If everything checks out, it does an ssh to the course account and runs a script there.
  • That script changes to a local git repo, pulls master, and runs Hugo. Hugo puts the output directly into public_html.
Edit | Attach | Watch | Print version | History: r5 < r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r5 - 2020-01-08 - ByronWeberBecker
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback