The InterpretingDL project website¹

This README needs updating

Jelle: This website was created by Marianne, reusing elements from the clclab website. Much of the text below is true for the clclab website, but not for the current one. In particular, updating the .md files in `source' or in the root has no effect. For now, my limited markdown/jekyll skills mean that any required changes must be made directly in the html files. (The only effect the .md-files had is causing jekyll to fail on the github server, so that the website did not get automatically updated. I had removed all 'cite' commands from the people.md file in the root, which solves that automatic updating issue, although I still get error messages by email when an update is pushed. ).

Introduction

The website is running through Github Pages at interpretingdl.github.io (note: www.interpretingdl.github.io does not work). In brief, it is a static website generated by a piece of software called Jekyll. This is both low-tech and techy: no Wordpress, databases, log-in and fancy stuff, but just simple text files (markdown).

Editing the website

What does Jekyll do? It generates a website based on what we put in the folder source. So to update the website, we have to do two things: (1) change something in the folder source (for example the contents of one of the webpages). Then (2) run Jekyll to generate an updated version of the website. This means that new changes to the repository are not directly visible on the website. Step (2) is described below under Technicalities.

How is the site structured?

You should only look inside the folder source, the other files in the root directory are automatically generated by Jekyll when building the site.

Some files you might want to make changes in:

• index.md -- the contents of the homepage
• other .md files, usually in _pages/ -- the other pages of the website (so far: members, methods, key papers)
• the interpretingdl.bib file in publications/ -- the BibTeX file with all references
• if you want to upload an image, it should go in assets/images/

Page structure

Jekyll files typically start with a header (between three dashes) with properties of the document (title, categories, etc), in YAML. These three dashes are important: they signal to Jekyll that it has to process the file. It is probably best to leave the header as-is when you are editing a page.

Here's the bare minimum:

---
# some properties, like:
title: An example document
permalink: /example
---

Contents of the document (in markdown)

# A header

And some more **boldface** text or *italic* text. You can also add some HTML, e.g.
<img style="float: left" src="../assets/images/example.jpg">

Questions or problems?

If there's a problem with the website, please create a new issue.

Technicalities

Setup

The website is a static website generated by Jekyll. To change the contents you have to edit markdown (or sometimes YAML) files. If you want to view the website locally from your computer, you can run bundle exec jekyll serve in your terminal (inside the source/ directory). Then copy the given 'Server address' to your browser to view your beautiful creation.

To build a version of the website that can be read by Github Pages and served to visitors:

1. Run jekyll build in your terminal (inside the source/ directory). Jekyll then builds a website based on the contents of the source directory into a folder called _site/.
2. In order to serve this new build to visitors, we overwrite the files in the root directory with the contents of of _site/. So the files in the root directory are never edited manually.
3. Push these changes to the github repository. After that, the changes should be visible online.

---

[1] I copied and adjusted this README from the one written for the clclab website by Bas Cornelissen -- this website works similarly (but also slightly differently).