Newer
Older
layout: page
This readme file is published in its fully rendered form [on the website]({{site.baseurl}}{% link README.md %}).
The source code for [this site](https://vtss.doc.ic.ac.uk) is [hosted on the DoC GitLab server](https://gitlab.doc.ic.ac.uk/resource-reasoning/vtss.doc.ic.ac.uk),
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**
[](https://gitlab.doc.ic.ac.uk/resource-reasoning/vtss.doc.ic.ac.uk/commits/master)
[](https://gemnasium.com/6ba7afbbfda9adcba06f007cc565a29a)
### Publications
Please see [the dedicated publications repository](https://gitlab.doc.ic.ac.uk/resource-reasoning/publications) for
instructions on how to add new publications to the website.
This website is built using the [Jekyll](http://jekyllrb.com/) website framework.
Pages can be written using
[Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) (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](https://jekyllrb.com/docs/frontmatter/).
For example, to set the page title and it's URL:
```yaml
* `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.
Jekyll Scholar Configuration Detail
===================================
We desire the output URL structure to be:
* `/publications/`
* `index.html` - a page listing the entire bibliography
* `publications.bib` - the raw bibtex file, directly from the source
* `Key.html` - details page generated for each publication
* `Key.*` - Any files associated with each publication, copied directly from the source
In the `scholar` section of the configuration file, configuration options we've used are:
* `source`: Directory in which our bibtex files are to be found (`publications`)
* `details_dir`: Directory to output `Key.html` files for each publication (`publications`), rendered using the layout
defined in the `details_layout` option.
* `details_link`: We override the default here, as we generate our own HTML to render this link in our
`bibliography_template`.
* `repository`: Location of files associated with publications (`publications`) (the same
directory is used for both input and output: it is handled as usual by jekyll)
The template used to generate individual publication pages is [here](_layouts/publication.html). The part of interest is
the Source Materials section. We iterate through a
[predefined list of file types](publications/_publication_file_types.yml) and output a link (using icon and text from
the file type list) to the file in the repository if it exists.
Finally, in order to generate the complete biography page, we use a [page](publications.html) in the site's root just
outputting a `{% bibliography %}` as normal (which renders each entry using the layout defined by the scholar
`bibliography_template` option). By using a `permalink` jekyll option we place the rendered bibliography into the
`/publications/` output directory as `index.html`.
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 should be deployed automatically by GitLab CI. To deploy the site manually from your own machine, run the `.deploy.sh` script. This will use `rsync` to synchronise the contents of the `_site` directory with the webserver via SSH. Default deployment parameters:
* DOC_DEPLOY_USER: the default username used by SSH to connect, usually the username on your local machine
* DOC_DEPLOY_SERVER: `shell1.doc.ic.ac.uk`
* DOC_DEPLOY_PATH: `/vol/rr/www`
To override these parameters, set shell variables, eg: `DOC_DEPLOY_USER=me ./.deploy.sh`
The site is deployed to `/vol/rr/www` automatically on successful build using the `.deploy.sh` script.
The contents of the `DOC_DEPLOY_KEY` CI environment variable are used
as the private key used to authenticate with the server. This key is currently configured to give locked-down rsync access to the
`/vol/rr/www` using `pg`'s user account. For further details for how this is achieved, [see this
howto](https://www.guyrutenberg.com/2014/01/14/restricting-ssh-access-to-rsync/). Note: when deploying to a locked-down
rsync account, the DOC_DEPLOY_PATH should be set to a path relative to the lockdown path -- use `.` if in doubt. You
won't need to set this if you're deploying from your own user account.
Locally Building and Testing
----------------------------
If you wish to test the site locally, ensure you have ruby installed, and then initially run:
```
```
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
```