Skip to content

Introduction

Jump to bottom
jenniferward edited this page Dec 9, 2020 · 56 revisions

Structure

The content of the website is entirely stored in this GitHub repository. This includes all source files, image files, and a complete history of all the changes.

Pages

Pages of the website are stored directly in the repository at the root level (e.g. home.en.md, or community.en.md) or in sub-directories (e.g., community/muscat.en.md). There is one page in the root level for each section of the website, and for sections that have additional sub-pages, one directory per section. Same applies for sub-sections (See publications)

Most pages are in Markdown, with a .md extension. See syntax below for more information about it. In some cases, HTML might be required but this is very rare and can very often be avoided, which maximizes readability.

There is one file per language (e.g., home.en.md for the English version, and home.de.md for the German one). See translations below for more information about how this works.

News

All the news are stored in the _posts directory. The news are organized by language (en, de, fr) and grouped by year-month (2020-12). Each news is one Markdown file. See News from more details about the organization of the News.

Resources

All resource files (images, pdf files) are stored in the images and resources directories. It is recommended to keep a directory structure mapping the one of the pages using or referring the resource files. For example, images in the community pages are to be stored in a images/community directory.

News images are stored in images/news and grouped by year-month (2020-12).

Resources migrated from the old website

Images and resources migrated from the old website are in resources-old-website. Images of the news of the old website are in images/news-old-website. No new additional files should be added in these directories.

Other files

The _data directory contains various configuration files:

  • the navigation.yml file stores the top-level navigation bar with the sections of the website
  • the locales.yml file stores some translations (e.g., News navigation labels)
  • the categories.yml file stores the news categories and their translations
  • all other *.yml files store submenus to be displayed as a sidebar

The _includes/sidepanels directory contains the files for the sidepanels to be displayed in a corresponding section layout template (e.g., organization, publications).

Syntax

Markdown

Most of the content of the website is in Markdown. Checkout the Markdown Cheatsheet for a good introduction to the syntax.

Jekyll

The site generator is Jekyll, which compiles the content of this repository into the website. Files to be processed by Jekyll include a front matter delimited with ---. It typically looks like:

---
title: RISM
layout: home-rism-info
lang: en
permalink: /index.html
---

The items of the front matter are:

  • title: the title of the page in the language of the page
  • layout: the layout template for that page, typically corresponding to the section (e.g., community, publications)
  • lang: the language of the page
  • permalink: the url for the page, always to be given without the language prefix. That is, the value /index.html with yield the page https://www.rism.info/index.html for en (because it is the default language of the website) and https://www.rism.info/de/index.html if the language is de, without /de in the permalink of the front matter.

Additional templates

In addition to Markdown, we use a couple of additional templates. One of them is image for showing small images at the top left or top right of a text paragraph. It needs to be placed before the paragraph and should be called with:

{% include image file="/path/to/the/image.png" pos="right" %}

The Editorial Center (Zentralredaktion) is the contact point for participants [...]

which will yield the following layout:

image

Blank links

In some cases, it is desirable to open links in a new window. For this we need to append {:blank} to the Markdown link. This means:

This [link](http://example.com){:blank} will open in a new window.

Translations

The website is multi-lingual. The default language in English, with German and French as other possible languages. This means that for every url (e.g., permalink in the front matter), the page will exist as is for the English, and under a prefix /xx for a translation (respectively de or fr).

For example, the pages publications.en.md and publications.de.md are accessible under (https://www.rism.info/publications.html for the first one (English) and under (https://www.rism.info/de/publications.html for the second (German).

If a translation is not available, the English is used as fallback. For example, the page (https://www.rism.info/fr/publications.html shows the English version because no publications.fr.md page exsits. However, users will remain in the French part of the website when they navigate further. (Other parts of the page, such as the links or the sidebar will be translated if the translation exists.)

Links

Links referring to other pages in the website are translated automatically and no language prefix should be inserted. For example, in publications.de.md, the link to the /de/community/sigla.html page is simply given by [link](/community/sigla.html), and the /de prefix will be added automatically by the site generator.

If there is a need, for some reasons, to have a link not translated, then a space ' ' should be added before the link value: [link]( /community/sigla.html)

Clone this wiki locally