published |
---|
This is a Jekyll template that is intended to mimic the functionality an appearance of the ucampas system, with a few helpful extensions. It is not officially supported by the University or the Computer Lab.
This template requires Jekyll Scholar, in addition to Jekyll. This is used to format the publications lists. As Jekyll Scholar depends on Jekyll, you should be able to install all dependencies (on a system with Ruby installed) with this command:
$ [sudo] gem install jekyll-scholar
This template uses Jekyll, so using it requires a little bit of understanding of Jekyll. Jekyll can run a local web server that will automatically update the generated pages based on changes to the source:
$ jekyll serve
This mode is primarily intended for development, so that you can see a live preview while editing. Once the site is ready for publication, run:
$ jekyll build
Note that if you are deploying to GitHub Pages and not using any of the Jekyll Scholar (BibTeX) functionality, then you can skip this step and just git push
.
Beyond this simple usage, it's important to understand a few things about how Jekyll works:
- Files (and directories) that start with an underscore are not pushed to the site, though they can be included in files that are.
- Files that do not start with an underscore will be pushed to the site, after preprocessing (if applicable).
- Files that are preprocessed should start with a frontmatter section. This is a yaml dictionary inside a block delimited by
---
. See the top of this file for a simple example. - Files in Jekyll that are preprocessed are typically constructed in two stages:
To give a concrete example, if you are using this template to generate a personal web page, you will use something based on index.markdown
file as your front page.
This has frontmatter saying layout: userpage
, so Jekyll will start producing an index.html
using the contents of _layouts/userpage.html
, with the contents of index.markdown
(now translated into HTML) as its contents
property.
The _layouts/userpage.html
file also provides a layout (default
), so the structure of the final page will be _layouts/default.html
at the top level, with _layouts/userpage.html
embedded in the {{ contents }}
liquid directive.
This, in turn, will have the HTML generated from index.markdown
embedded in its {{ contents }}
directive.
Each of these steps can also involve other inclusions.
For example, the default
layout uses head.html
, header.html
, and footer.html
as include sources, providing consistent layout across different page styles.
Items in the frontmatter can also determine how the page is rendered.
For example, if the frontmatter for a page using the default
layout (directly or indirectly) contains a github: foo
element, then the page will have a 'view on GitHub' button linking to that organisation or project on GitHub.
To use this template, clone the git repository and modify a few files. If you intend to use this for a personal home page, then:
- Add a
photo.jpg
to the root directory with your picture. - Modify
_config.yaml
with your name in the relevant fields and your CRSID in the base URL. - Edit
_data/author.yml
with your name, office, and phone number. - Replace
_bibliography/publications.bib
with a BibTeX file containing your own publications. - Edit
index.markdown
to describe your research and intersts.
If you are creating some other family of pages, then you will want to change
index.markdown
to use the default
layout, rather than userpage
. You may
also want to edit _data/breadcrumbs.yml
, which contains an array of pages to
reference in the root set of breadcrumbs.
If you wish to hide pages, then you can either delete the corresponding file or
set published: false
in the YAML frontmatter (the bit between ---
lines at
the start).
Once you have done this, simply run jekyll build
to get a public_html
directory containing your site. While testing, use jekyll serve
to run a
temporary local web server for previewing your in-progress edits.
The publication lists (both the complete publications page and the short
summary on the user page) are generated from _bibliography/publications.bib
.
If you have set the pubauthor
field in _config.yml
then this name will be
italicised in all publications. For group web sites, pubauthor
can be an
array and all names will be italicised.
The title will become a link if there is a url
, pdf
, or doi
field in the
BibTeX entry. If there is an abstract
field then the accompanying text will
be shown inline, in a hidden section, exposed by clicking on the [abstract]
link. A pretty-printed version of the BibTeX will be exposed in a similar fashion.
The _projects
directory should contain one file for each project. These are
normal Jekyll files and their title should contain the following entries in
their frontmatter:
title
, the title of the project.type
, the type of projects (2, 3, or phd, for Part II, Part III/ACS, or PhD project ideas, respectively).presequisites
Any prerequisites for the project.done
(optional), set totrue
for completed projects that you wish to show on the 'Selected past projects' page.outcome
(optional), a summary of the outcome for completed projects.
These will then be aggregated into the various pages in the Projects section.
Any subdirectory with an index.markdown
(or index.html
if you want to write
the HTML yourself) will be an entry in the site contents bar on the left. Any
other files in the directory will be subtopics.
This template only supports a single layer of nesting.
If you wish to insert a table of contents for a single page, then include the contents file:
{% include contents.markdown %}
This will use the ucampas style, including the animations for selected titles.
A table of contents for the site will be generated automatically. If you want
to customise it, then create a _datacontents.yml
file. This should contain
an array of objects with two required properties (title
and location
) and
one optional property (subheadings
). The title
contains the display name
of the heading, which should match the title of a page. The location is either
an absolute URL or the name of a directory at the top level.
The subheadings
array can contain names of files (with or without their
suffixes) within the section directory, or objects containing a title
and
location
.
If you have a page that describes a project on GitHub, the set the github
property in the YAML frontmatter. This project would have something like this:
---
github: davidchisnall/camtemplate
---
The page will then have small buttons for viewing the project page on GitHub and downloading tarballs inserted. You can also provide just the name of an organisation, for example:
---
github: davidchisnall
---
In this case, the 'view on github' button will appear, linking to the organisation but the download links will not.
If you are using this template for a project or group page, then you will
probably want to have a 'people' page. There is a template people page in
people.markdown
, which contains some examples. Delete the published: false
line at the top of this file to see how it looks.
Each person in your project should have a separate file in _people
.
As with other Jekyll files, this starts with YAML frontmatter, which should
contain the following keys:
role
: The person's role within the project. This is used to define different
categories of person for inclusion in different sections of the page.
photo
: The URL of the person's photo.
name
: The person's name, as they would like it to appear.
homepage
: The URL that this person's name should be linked to.
The remainder of the file contains descriptive text (only used in the verbose
format). To define a list of people, include the people.html
file. You may
optionally including a role
and style
option. For example:
{% include people.html role='PI' style='verbose' %}
This will include all people whose role in the project is PI
(a string
identifier - you may use any role names that you wish), with the verbose
layout. If role
is omitted, then everyone will be included. There are three
different layouts currently available:
verbose
: One person per line, with the photo on the left and the descriptive text on
the right.
brief
: A three-column list, containing only the names (no photo or long description).
default
: The view presented if no style is specified. This lists photos with names
underneath, for the width of the page.