Skip to content

Home

Jump to bottom
Christopher Aicher edited this page Aug 20, 2016 · 2 revisions

Sol Stat Website Guide

This is a guide to our GitHub Pages website found at https://solstat.github.io.

About the Website

The Solstat website is hosted on GitHubPages and is built using Jekyll. The website code can be found at its GitHub repository https://github.com/solstat/solstat.github.io/. Use Git to fork the repository.

The repository consists of two branches: master and source.

The source repo maintains the files, images, and code that Jekyll uses to build the website.
The master repo maintains the actual <html> files that are built by Jekyll (the files in _site/).

Adding Content to the Website

To add content to the website, you must "fork" the website repository and make a "pull request". All changes should be made in the source branch.

A step by step guide to forking repositories and making pull requests can be found on GitHub Help at fork-a-repo. Read the help page first, then read the steps below.

  • For small changes, you can make changes and edits to your forked repository through your browser.

  • For larger changes and to preview changes to the website, you can clone your fork and make local changes and commits to source branch. (You should be on the source branch by default, but double check). To preview changes to the website by building the source branch locally using Jekyll (see below).

After completing your edits, the final step is to make a pull request for the source branch. Before making the pull request, make sure to check that your forked repository is in sync with the original (see synching-a-fork ). To keep your forked repository in sync, make sure to add the original repository as upstream. Then call git merge upstream/source from the source branch to pull changes.

Finally to make the pull request, push your local changes to your forked repository git push origin source, then follow the steps of using-pull-requests in your browser. You should only be making pull requests on the source branch. The pull request allows other members to see what changes have been made before it goes public.

Approving pull requests

After a pull request is made, someone with Jekyll must verify there are no errors, by building the proposed site locally. If everything checks out, then approve the pull request.

There is one additional step in updating content to the live Website. After source changes are merged in, someone must update the master branch (the master branch is what's hosted by GitHub and public).

Updating the master branch requires using Jekyll to build the website's <html> files. The script deploy_to_master.sh (called from the source branch) will execute a Rakefile to update the master branch. This will copy the /_site folder of the source branch to master.

Remember: Changes to master affect the live website

Building a Local Copy of the Website

This section describes how to build a local copy of the website using Jekyll.

First clone the repository to your machine.

Using Bundler (preferred)

gem install bundler
bundle install
bundle exec jekyll serve

Using Jekyll

Then follow the instructions here to setup Jekyll for GitHubPages. This may involve installing Ruby.

To build a local copy of the website, call jekyll serve (in the source branch) and open a browser to http://localhost:4000/. If you receive errors make sure you have run bundle install first. If the errors persist try using the command bundle exec jekyll serve.

To build a local copy of website without viewing it, call jekyll build (or bundle exec jekyll build).

How to add yourself to the People page

First add your info to _data/authors.yml. Note that indentation is important here.

Create a userid and then add your info as fields (the document has examples). Required fields are

  • name - your name
  • web - a url to your website (don't forget to include https)
  • bio - a few line bio
  • avatar - filename or url to a photo of yourself

Second place your avatar photo in the /images folder. This photo will be adjusted to a 1:1 square aspect ratio, so crop accordingly. Note: the image must have the filename specified in the avatar field.

Finally, edit the people/index.md by adding the following line {%include _bio-template.html userid="<userid>" %}, where <userid> is the userid you created in _data/authors.yml.

How to add a Publication

Add the bibtex of your publication to _bibliography/pubs.bib (make sure you are on the source branch).

Then either:

  • Add a hyperlink to a pdf copy of the publication using the link field in the bibtex.
  • Add a pdf copy of the publication to the pdf/ folder with the name [bibtexkey].pdf
  • If you want to add link to your code, Add a hyperlink to a your code using the code field in the bibtex.

Advanced Details

We use the Jekyll Scholar plugin to manage and build our publications page. BibTex formatting is controlled in the _config.yml file (style) and in the _layout/bib.html file (url, bibtex popup). Layout of the publications page is controlled by publications/index.md. See Jekyll Scholar for more tips.

How to add a Project

To do

How to add a Blog Post

To do

Adding Math Using MathJax

To do

Adding References Using Jekyll Scholar

Involves using the liquid tags.

See Jekyll Scholar for more tips.

Useful References

The website is hosted by GitHub. For more details on GitHub Pages see Link and Jekyll (the backend software that runs it) Link.

The website theme is based of the Minimal Mistakes theme by Michael Rose Link. The sample posts offer good tips on how to add and author posts.

Clone this wiki locally