Repository holding the sources of the KWARC.info website

Note for authors: When editing some text, please do not hard wrap existing lines. This plays very bad with diffs, in particular an entire paragraph shows up as changed even though it might just be a single line. Furthermore, this introduces lots and lots of merge conflicts Markdown (similar to TeX) only inserts actual line breaks when making to link breaks in the source file. Thus the most readable and diff-compatible option is to write one sentence per line and use soft-wrapping on top in editors. This is called semantic linefeeds.

About

This website is built statically from Markdown source files using Jekyll. To update a page, just modify the corresponding source and push. This can be done online by clicking on Edit this page in the navigation menu. See the above links for details.

• _config.yml: main configuration page
• _includes/*: reusable chunks of web pages, like the nav bar
• _layouts/*: local style files
• _post/*.md: sources of the news, blog posts and activities
• news/*: the KWARC news are generated here.
• people/*.md: the KWARC home pages
• projects/*.md: the KWARC project descriptions
• public/*: all static files (images, js, css, etc)
• public/*.md: descriptions of the research areas
• systems/*.md: descriptions of the KWARC sytems
• courses/*.md: KWARC courses (this may be obsoleted by univis)

Performance

This jekyll page is tuned in order to build as fast as possible. It also makes use of the jekyll-compress-html layout, to be efficiently transferable over network. During the evolution of the website, the build time has changed dramatically. It used to take around 5 minutes to build, with a few optimizations it now only takes up 15 seconds.

The biggest slowdowns were:

• unneeded iterations
  • iterations within iterations (usually not required, if one thinks carefully)
  • if conditions within a loop, instead of a where clause
  • full iteration to extract a single item (use first instead)
• repeated sorting of site.pages by the same menu_order key (instead sort this once and use a global variable)
• multiple chained ifs instead of a single and
• unneeded variable assignments (these seem to take a lot of time in liquid)

How to use Jekyll to test/build this website

This is a static website automatically generated with Jekyll by GitHub Pages.

Editing pages online with GitHub / GitLab

You can edit any page by following the Edit this page link in the Quick links nav bar. Alternatively, you can directly navigate to the corresponding .md (Markdown) file in GitHub.

This will drop you in GitHub's file editing interface, where you can modify the source code, preview it, and save your changes, by giving ashort description of what you modified. If you have write access to the repository (hint: you do), your modifications will be published rightaway. If you do not have right access, you will be asked to fork the repository and make a pull request.

Most of the pages are written in Markdown, which is a textual format for generating formatted text. Markdown syntax is very intuitive, you can get a quick review here or here.

CAVEATS: The Markdown engine used by this site is Kramdown. Its syntax definitions are slightly different from GitHub Flavored Markdown, thus the preview feature in GitHub might not render source as in the final result.

Other reasons why GitHub's preview may not correspond to the final results are:

• Use of Liquid templates in the source.
• Use of special purpose markup, HTML, and scripts, such as mathematical excerpts written in MathJax.

Editing the menu

The menu of the page is defined in the _config.yml file. It consists of a set of items, that are defined by the following keys:

• url - The (internal or external) url to the page. If internal, must be relative to the root directory.
• active - URL to a folder under which the item should automatically be expanded (if applicable).
• folder - Instead of using url, the folder can be used to create a submenu pointing to a specific folder.
• items - A list of items for submenus.
• external - If set to true, assumes that url is external to the page.
• menu_title and title - Title to be used in the menu item.
• menu_hidden - If set to true, hide the item from the menu.
• menu_order - By default, menus are ordered in the order they are listed in the menu. This key can be used to override the order. Values must be non-negative integers between 0 and 10000 (inclusive). The default value is 100.

Singular items can be inserted as following:

# A single link to the /news/ page. 
- menu_title: 'News'
  url: '/news/'
# An external link to the bibliography page
- menu_title: 'Bibliography'
  menu_external: true
  url: 'https://kwarc.github.io/bibs/'

Submenus. The menu allows (up to) one level of submenus. There are three such cases:

1. An item specifies the folder key. In this case all pages in the given folder are automatically added. The frontmatter is used for the specification.
2. An item specifies the items key. Here the items are used accordingly.
3. An item specifies both the folder and items keys. The items for both cases are automatically merged.

Because submenus are not clickable, the url for submenus is ignored when building the menu. Furthermore, if these are mixed between folders and static items, the folders will always show first.

# A listing of the folder submenu
- menu_title: 'People'
  folder: '/people/'
# A submenu of university links
- menu_title: 'FAU links'
  items:
    - menu_title: 'Overview'
      external: true
      url: 'https://fau.de/'
    - menu_title: 'CS department'
      external: true
      url: 'https://cs.fau.de/'

A submenu is automatically expanded if any of the submenu items inside it are clicked. Alternatively, if the menu item contains an active key, it is checked as well.

Working locally

If you want to do more than the occasional editing, you'll soon realise GitHub's editor and preview are too limited. It's better to work locally on your computer.

All you need to work locally is a Git client. Clone the repository and start coding right away.

At some point, you will need to preview your work, but pushing to GitHub each time you want to preview is clumsy. Your best option is to install Jekyll and the required dependencies on your machine. It is recommended to install the GitHub pages gem which provides you with the exact same versions used by GitHub to compile your site.

If you already have Ruby, the install part should be as easy as

gem install bundler
bundle install

in the local clone of this repository.

Note that you will need Ruby headers (ruby-dev package on Ubuntu) in order to compile C dependencies.

You can then run the development server by:

bundle exec jekyll serve

Your site will be generated in a _site sub-directory, and served live at http://localhost:4000/.

Have fun!