/mlrg

MathLing Reading Group Website

Primary LanguageHTML

MathLing Reading Group Website

This repository holds the Pelican source files for the MathLing Reading Group website. These are simple markdown files that are automatically converted into HTML via the Python-based Pelican and then uploaded to Github with ghp-import.

System Requirements

If you're affiliated with Stony Brook University, you can download a virtual machine image that comes with all necessary packages pre-installed. This image hasn't been updated in a while, but it should be new enough to compile the website just fine.

  1. Recent version of Python3.

  2. Pelican 4.0 or higher. Under Linux, this might already be in your repository.

    • In Debian Jessie and older releases you have to activate the backports repository to get a recent version. The recent Debian Stable release already has Pelican 4.
    • In Ubuntu you might have to find a ppa or use the Mac/Windows method.
    • On OSX and Windows (and Linux, if necessary) you can install Pelican via Python's package manager pip.
    pip install pelican

  3. The ghp-import script. Again you can install it via pip

    pip install ghp-import

    or use your package manager if you're on Linux.

  4. A recent-ish version of the make tool. This is usually already installed on Linux and OSX. If it isn't, make sure you have the basic tools for compiling software installed. On Debian and Ubuntu, the following should work:

    sudo aptitutde install build-essential

    On Windows, install GnuWin32 or MinGW. The make binary also has to be in your PATH, which happens automatically on Linux and OSX but not Windows.

  5. Python's typogrify library. This is no longer needed

A Note on pip Installations

Python's pip has the nasty habit of scattering the install files across various system folders. A better solution is to create a virtual environment in your home directory that holds all the files related to working with pelican:

mkdir ~/.mlrg_env
python -m venv ~/.mlrg_env
~/.mlrg_env/bin/pip install pelican ghp-import

You then have to make the pelican script accessible through your shell, either by adding ~/.mlrg_env to your PATH or by symlinking it to a folder in your PATH (e.g. /usr/bin or ~/bin).

File Structure

Once you've cloned the repository, you'll see a couple of files and folders. The most important ones are:

  • content: the markdown files for the website
  • output: the actual website generated by Pelican
  • pelicanconf.py: contains various settings for site creation; do not change unless you know what you're doing
  • publishconf.py: allows you to override certain settings in the final creation phase; do not change unless you know what you're doing
  • Makefile: set of instructions for building the website

Workflow

Creating a new announcement is easy.

  1. Go to the folder content and then the folder for the current semester (e.g. 2016-Spring).
  2. Create a new markdown file.
  3. Make sure the markdown file starts with a well-formed header with the first three lines consisting of Title:, Author:, and Date: (in format YYYY-MM-DD), followed by an empty line.

To test things locally before you upload them, you have to

  1. open a terminal and navigate to the root folder of the repository (the one with pelicanconf.py),
  2. run make devserver, and
  3. open a browser and load http://localhost:8000.

If everything is fine, run make stopserver to end the testing phase. Now only two things remain:

  1. upload the website by running make github, and
  2. sync the source files to the repository:
    • git add .
    • git commit
    • git push origin master