Undergraduate Projects Lab Website
This website is powered by jekyll. Contributions and issue reports are welcomed!
Before making any changes, be aware of the following:
1. If you're changing a file in
images/, you can commit to master
2. If you're changing anything else, make a pull request to the develop branch.
If your commit skips the development/review process, expect it to be reverted.
This project uses the official GitHub Pages gem. This manages all of the project dependencies for you, as long as you have a working version of Ruby and Bundler.
On a Unix-like OS, I recommend using rbenv to install a new version of Ruby. Follow the instructions in that README and then enter the following:
$ gem install bundler
To install Jekyll and the other dependencies, navigate to the project directory in a shell and type
$ bundle install
To run the development server, navigate to the project directory in a shell and type
$ jekyll serve --config _config.yml,_config.dev.yml
This will launch a local server on port 4000 -- see
_config.dev.yml if you intend
to change this for yourself.
Setting up a dev environment on windows
While there are ways to get jekyll working natively on windows, it's not the most reliable system in the world. This section should detail the reproducable steps necessary to get it working. These steps will rely on the windows 10 llinux subshell and native bash. For information on how to enable the linux subsystem and install bash, go here
(It's assumed that you've already cloned the repo to somewhere)
- Install ruby
sudo apt-add-repository ppa:brightbox/ruby-ng
sudo apt update
sudo apt install ruby2.3 ruby2.3-dev ruby-switch
ruby-switch --set ruby2.3
- Install main gems
gem install jekyll -v 3.1.6
sudo apt-get install libxml2
- This might not be necessary but I didn't want to uninstall this package to see if the installation succeeded without it.
sudo apt-get install zlib1g-dev
gem install github-pages
- When it says "This could take a while..." it means it.
- Install proper gem version
- I don't know anyway of getting around running these commands but it made mine work. Try running the last command here first and seeing if that fixes the issue.
sudo gem install colorator -v 0.1
sudo gem install jekyll-mentions -v 1.1.3
sudo gem install terminal-table -v 1.6.0
sudo gem install github-pages -v 91
- Install node 6
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
- Add alias to bashrc to build and serve jekyll site
alias uwjekyll='bundle exec jekyll build; bundle exec jekyll serve --config _config.yml, _config.dev.yml --no-watch'
- You'll use this alias to build and serve the site. Until some things that jekyll uses have compatibility issues resolved this is necessary.
How to do common things
By far, the most common kind of change is one you make to the site's data. This includes:
- Changing your office hours
- Adding a project or an event
- Adding or changing an image
- Changing your favorite emoji (coords only!)
All of these can be done by modifying the respective files in
one exception: images are located in
images/. Both of these locations follow
standard Jekyll practices.
Changing page layout
Each page has a corresponding
.md file in the top-level project directory.
If you want to change the templates used to make these pages, start here.
Adding client-side scripting
For the most part, the site's content is fully static -- that is, never changing after
the site has been generated. However, some things cannot be generated like this --
for example, the lab status page needs to make an AJAX call to a remote service. The
principle we follow now is to make the template define an incomplete version of the
page statically and to embellish it with a script.
lab.html is an example of this.