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: Files read by templates in the course of generating the site can go here. Currently it stores data to generate the self-check exercises.
  • 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.
  • deploy: script used to generate the site and deploy it to public_html. Do not change without direction from permanent staff.
  • deployVars: Variables used by deploy to generate the site. This is where to go to change which lecture modules are displayed, for example.

How to update the web site

Working on the web site works best if you can work LOCALLY. That is, not SSHing to the course account. Unfortunately, ISAs are not currently able to do this.

One-time setup:

  1. Checkout the repo to your own machine: svn co svn+ssh://cs135i@linux.student.cs.uwaterloo.ca/svnrepo/web. You must have an ssh key in the cs135i account and appropriate svn permissions.
  2. Ensure that Hugo (the static site generator) is installed
    1. Do a which hugo to see if it's installed
    2. If not, go to the Hugo site and install it. IMPORTANT: You need the "extended" version of Hugo. I think that's what the following does, but not positive. If you get errors with SASS, then you don't have the extended version.
      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...
Alternate method for editting the repo already installed on the cs135 course account:
  1. Connect from your local machine to your student account via ssh
    • If you're on a Mac, you can open terminal and enter the following command: "ssh -L 1081:localhost:1080 <youruserid>@linux.student.cs.uwaterloo.ca"
    • If you're using cygwin on Windows, the above command should work as well, but this hasn't been tested yet.
    • If you're using PuTTY on Windows, you'll need to accomplish the same idea but using its Tunneling feature.
      1. From the PuTTY Configuration's Category menu, go to Connection->SSH->Tunnels
      2. In the 'Source Port' field enter '1081' and in the Destination field enter 'localhost:1080'. Then click the 'Add' button to save this port-forwarding option.
      3. Save this configuration (via Session in the Category menu) so that you don't need to configure this tunnel everytime you want to connect to the course account. You'll likely also want to save your 'Host Name' as 'linux.student.cs.uwaterloo.ca' along with any other options you like to configure PuTTY with.
  2. Connect from your student account to the cs135 course account via "ssh -L 1080:localhost:1313 cs135@linux.student.cs.uwaterloo.ca"
The idea of the above steps is to ensure that when you later want to access content in your browser that is local to the course account on port 1313, this information gets redirected through port 1080 on your student account to your local computer's 1081 port. You can then view this content in your browser (e.g., Chrome) by entering "http://localhost:1081/~cs135/" in your browser's search bar. See the below descriptions of the editing process for locally checking the results of edits you make.

Do the update to the website:

  1. Do a fetch in the repo to make sure you have the latest version of the web site. (svn up).
  2. Find the right page, almost certainly in the contents directory mentioned above. Pay attention to the 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. If you make further changes to the website files while hugo serve is running, it should automatically detect the changes and regenerate the website (you'll need to refresh the page in your browser) so you won't need to halt and re-run hugo serve if you're making multiple edits at once. Changes to scripts probably can't be checked this way; but you probably won't be making changes to scripts smile
  5. You can run 'svn status' to generate a list of the files that you've locally changed - make sure you're not changing/adding something by accident that you don't intend to. When all is good, commit your changes. A script will automatically update the web site.

Other Tasks

Releasing additional lecture Modules

The deployVars file in the web_commit directory contains variables read by the deploy script. Currently it has only one, hideLectureStart. This questionably named variable is the one to change. Lecture modules starting with that number will be hidden. It is NOT under version control so that the one in the student site can be different from the one in the test site. Change it and then run the deploy script, either manually or by commiting other changes to the svn repo.

The part of this that is not automated and must be done manually is to update the overview web page in `/content/cc/lectures/_index.md`.

Steppers

Which steppers are shown is determined by `/web/static/stepping/questions/problem-list.php`. It's pretty primitive: lines are either commented out or not. The deploy script, when used in the test account, uncomments all of them. Not very robust.

The actual organization of the steppers is determined by the subdirectories in `/web/static/stepping/qsrc`.

Implementation Details

The contents of the web site (except for videos) is stored in the course SVN repo in the cs135i account.

There is a working copy, web_commit, in the cs135 course account. It's use is only for deployment.

Other working copies, including one in the course account, are used to make updates to the web site -- and hopefully test them.

When changes in the working copies are committed to the repository, a "hook" for "commit events" runs. It calls a script in the CS135 account that updates the web_commit working copy and then runs the deploy script. The deploy script runs Hugo to generate the site putting the output in public_html. It also adjusts permissions, looks after .htaccess files, and copies some data files.

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. *
Edit | Attach | Watch | Print version | History: r11 < r10 < r9 < r8 < r7 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r11 - 2020-09-16 - BenHicks
 
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