Editing the website#

Introduction#

Most of this website is built from plain text files written in Markdown, compiled to HTML using a simple script and inserted into templates. To make changes to the website, you need a clone of the production repository and, if you want to test your changes, a working build environment.#

Getting started#

A few tools must be present to work on the website. You only need to run the steps in this section once.#

repos=/afs/hep.wisc.edu/code/git/repos
mkdir -p /scratch/$USER
git clone $repos/cmsops/www /scratch/$USER/www
cd /scratch/$USER/www

You now have a complete checkout of the website where you can edit and commit your changes. To actually build the site, though, you should create a sandbox and install a few tools:#

mkdir src
cd src
curl --location --output virtualenv-16.6.1.tar.gz https://github.com/pypa/virtualenv/tarball/16.6.1
tar xzf virtualenv-*.tar.gz
python3 *virtualenv*/virtualenv.py --distribute /scratch/$USER/www
cd ../
ln -s ./bin/activate ./setup.sh
. ./setup.sh

You’re now in the sandbox and can install Python packages without interfering with your system:#

pip install -r ./requirements.txt

This will install everything you need. Now you can build!#

Installing from a local mirror#

Building the site#

The build is controlled by a simple Makefile. Since the files are all independent of eachother, you can invoke make in parallel mode:#

make -j 8

This will build all of the .html files from the .txt.#

Viewing the results#

Fire up a simple web server that listens on port 8000:#

make serve

You’ll find the new website in your browser at http://localhost:8000/.#

Publishing your changes#

Once your changes are tested, commit them and push them to the main repository. Adjust the commit message to something describing what you did.#

git commit -m "Update to the website."
git push

The changes you made will not appear immediately on the website. A (cron job) automatically updates the website from the repository every 15 minutes on cron01.hep.wisc.edu.#

Updating your repository#

In the future, if you use the same clone of the repository that you created following the above instructions, you should synchronize it with the main repository before you make more changes.#

source ./setup.sh
git pull
git update

If you forget to synchronize your repository, or if somebody else is editing files at the same time as you, you may need to resolve a conflict with you push your changes. In the simplest case, merging the changes is as simple as this:#

git pull
git merge
git commit

Notification of changes#

Consider subscribing to notification emails sent when changes are made to the repository. To subscribe, add a line like the following to the [reposubs] section of the subscriptions file:#

**/cmsops/www = ${USER}

Style#

Though the Markdown syntax is fairly well documented, it is also very permissive. In addition, I propose we stick to the following arbitrary elements of style to improve consistency:#

  • When indenting, use four spaces instead of a single tab.
  • Text should be wrapped at 80 characters; lines that are wrapped should be indented
  • All pages should define a title in the leading metadata block (# The Title)
  • Paragraphs, headers, lists, code sections and other block elements should be followed by a single empty line.
  • Headers should be marked in the ATX style (## Second level header) as opposed to the Setext style (underline) and should not be closed with trailing hashes.
  • The first header on a page should be at level 1 (# First header).
  • Lists should be indented with a single space followed by the asterisk followed by another single space (* A list item).
  • List items should be wrapped with a hanging indent.
  • Horizontal rules should be spelled with three asterisks on a line (***)
  • Use reference links instead of inline links, making the id implicit when possible ([example][]).
  • Link definitions should follow the paragraph in which they’re used.
  • Use * and ** instead of _ and __ to denote emphasis.

Things to do#

For a quick check, use the online link checker run by the W3C. For more control over the process, install checklink and run it yourself using the checklink target. If you don’t want to install checklink globally, use local::lib to create a non-privileged area for Perl libraries (similar to virtualenv described above). Then:#

perl -MCPAN -e 'install LWP::Protocol::https'
perl -MCPAN -e 'install W3C::LinkChecker'

Garbage collect old pages#

Many pages on the site are old or outdated and can be removed. To remove such a page:#

hg rm oldpage.txt
sed -i -re '/oldpage \\/d' Makefile
hg commit -m "Remove oldpage, which is old." oldpage.txt Makefile