This readme file is published in its fully rendered form on the website.

The source code for this site is hosted on the DoC GitLab server, you should have access to edit it if a member of the resource-reasoning group.

DO NOT EDIT THE SOURCE CODE IN /vol/rr/www, IT IS ALL REPLACED EACH TIME THE SITE IS REBUILT FROM VERSION CONTROL

Build Status Dependency Status

Managing Content

Publications

File Downloads

Files associated with publications should be placed in the publications directory. The filename prefix must be the key used for the corresponding entry in the BibTeX file. The filename suffix (extension) determines how the file appears in the page listing. Unknown filetypes are permitted, but will be printed in a bland, not-very-descriptive way.

Known filename suffixes are defined in _data/publication_file_types.yml and are summarised in the table below:

ExtensionIconTextFile contents used as link?
.pdf Authors' Preprint
.techreport.pdf Technical Report
.zip File Archive (.zip)
.github.link Code Repository (GitHub)
.repo.link Code Repository

Technical Detail

This website is built using the Jekyll website framework. Pages can be written using Markdown (preferred) or HTML. Files should be named with the extension they’re writen in (.md, .markdown, .html, …), they’ll be compiled to .html versions of the file on publication. (Unless otherwise specified with the ‘permalink’ property of the page).

Pages to be interpreted by the Jekyll framework should be started with a YAML variable block. The variables here can be used to change properties of the page. For further details, see the Jekyll documentation. For example, to set the page title and it’s URL:

---
title: Page Name
permalink: /my-custom-page-path/
---

Variables that templates currently take into account are:

  • title, sets the page title
  • menu, (default: false) places the page into the website’s navigation menu
  • menu_order, decides the order of menu
  • parent_menu, creates a parent menu with a dropdown box including the current page. Pages with the same parent menu are put in the same box. Please also ensures the existence of parent_menu and its value, and menu_order are consistent.
  • sub_menu_order, decides the order of menu in corresponding dropdown box.
  • project_id, links the page to a project.
  • project, (please only use this for person, i.e. file under the directory of _people), links a person to a project.
  • firstname, lastname, position, webpage, email, github, describes a person.

The main content of the page should then follow.

Any other files present in the directory structure (except for those prefixed with _, ., or explicitly excluded in _config.yml) will be published unchanged to the website.

For the detail of adding publication, please refer to the README file in publication directory.

Testing and Deployment

The DoC GitLab instance is configured (using .gitlab-ci.yml) to build, test and deploy the website on tests passing. The tests run are to check that the build works (no critical syntax errors in templates), and that internal page links are consistent.

An additional check that external links are still live is also run, but this test is permitted to fail without blocking the deployment.

The site is deployed to /vol/rr/www automatically on successful build.

Locally Building and Testing

If you wish to test the site locally, ensure you have ruby installed, and then initially run:

gem install bundler
bundle install

And to start a local webserver that remakes files whenever changed:

bundle exec rake serve

You can test for dead links and html errors using:

bundle exec rake test