ops-class.org Website Sources

Installing and Building

1. Install node.js and npm, the node package manager.

   • I suggest you use nvm (the node version manager) or install node.js from source. The apt-get packages are fairly old.

2. Join the ops-class group on GitHub and add an SSH key.

3. git clone git@github.com:ops-class/www.git. If this doesn’t work, you probably don’t have a key installed. Return to Step 2.

4. cd www; make install

   • The first time this will take some time since npm install is running and performing some local compilation. Note that you also need ImageMagick installed locally to build the node packages. sudo apt-get install libmagick++-dev does the trick on Ubuntu 14.04.

5. make run, then open localhost:8080 in your browser.

6. When you edit, rerun make and the site will be rebuilt. make check will build and check the site.

7. I suggest a three terminal environment using tmux:

   1. An editing window.

   2. A window to run make or make check.

   3. A window to run make run to serve the sources.

Deploying

1. make check runs several sets of build-time checks:

   • Broken links by metalsmith-linkcheck. Broken external links will not fail the build but will generate a warning Broken internal links will.

   • Formatting checks by metalsmith-formatcheck. Format failures will fail the build, but I doubt you’ll be changing the format much.

   • Spelling checks by metalsmith-spellcheck. Spelling failures will halt the build.

   • I maintain all three of these Metalsmith plugins, so if you find bugs let me know.

2. If the build doesn’t complete, fix the problems and rerun make. Don’t push until the build completes.

3. Please check the links_failed.json file if it complains. Sometimes external broken links are a transient problem, but at least check to make sure that you understand what is failing.

4. To add spelling exceptions see the documentation for metalsmith-spellcheck. There are a bunch of ways to do this depending on the word that is being marked as misspelled.

5. Commit your changes to master.

6. Push to master. This triggers remote testing on Travis CI. It runs npm test, which in our case runs make check. If that does not fail, the sources on www.ops-class.org will be updated. This sometimes takes a few minutes.

7. If the build fails you should receive an email. The main site will not update. Please fix the problem and push again.

TODOs

• Add OS/161 man pages.