README.md 8.09 KB
Newer Older
Michael Kohlhase's avatar
Michael Kohlhase committed
1 2
# Repository holding the sources of the KWARC.info website

Tom Wiesing's avatar
Tom Wiesing committed
3 4 5
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
Tom Wiesing's avatar
Tom Wiesing committed
6 7 8
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](http://rhodesmill.org/brandon/2012/one-sentence-per-line/). 
Michael Kohlhase's avatar
Michael Kohlhase committed
9

Tom Wiesing's avatar
Tom Wiesing committed
10
## About
Michael Kohlhase's avatar
Michael Kohlhase committed
11

Tom Wiesing's avatar
Tom Wiesing committed
12 13 14 15
This website is built statically from Markdown source files using [Jekyll](http://jekyllrb.com/). 
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.
Michael Kohlhase's avatar
Michael Kohlhase committed
16

Tom Wiesing's avatar
Tom Wiesing committed
17
* `_config.yml`: main configuration page
Michael Kohlhase's avatar
Michael Kohlhase committed
18
* `_includes/*`: reusable chunks of web pages, like the nav bar 
Tom Wiesing's avatar
Tom Wiesing committed
19
* `_layouts/*`: local style files
Michael Kohlhase's avatar
Michael Kohlhase committed
20 21 22 23
* `_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
Tom Wiesing's avatar
Tom Wiesing committed
24
* `public/*`: all static files (images, js, css, etc)
Michael Kohlhase's avatar
Michael Kohlhase committed
25 26
* `public/*.md`: descriptions of the research areas
* `systems/*.md`: descriptions of the KWARC sytems 
27
* `courses/*.md`: KWARC courses (this may be obsoleted by univis)
Michael Kohlhase's avatar
Michael Kohlhase committed
28

Tom Wiesing's avatar
Tom Wiesing committed
29 30 31 32 33 34 35
## Performance
This jekyll page is tuned in order to build as fast as possible. 
It also makes use of the [jekyll-compress-html](https://github.com/penibelst/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:
Michael Kohlhase's avatar
itemize  
Michael Kohlhase committed
36 37

* unneeded iterations
Michael Kohlhase's avatar
Michael Kohlhase committed
38 39 40 41 42 43
   * 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 `if`s instead of a single `and`
* unneeded variable assignments (these seem to take a lot of time in liquid)
Tom Wiesing's avatar
Tom Wiesing committed
44

Michael Kohlhase's avatar
Michael Kohlhase committed
45 46
## How to use Jekyll to test/build this website

Tom Wiesing's avatar
Tom Wiesing committed
47
This is a [*static website*](http://en.wikipedia.org/wiki/Static_web_page) automatically generated with [Jekyll](http://jekyllrb.com/) by [GitHub Pages](http://pages.github.com/).
Michael Kohlhase's avatar
Michael Kohlhase committed
48

49
### Editing pages online with GitHub / GitLab
Michael Kohlhase's avatar
Michael Kohlhase committed
50

Tom Wiesing's avatar
Tom Wiesing committed
51 52 53 54 55 56 57 58 59
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](https://help.github.com/articles/what-are-the-different-access-permissions/) 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](https://help.github.com/articles/fork-a-repo/).

Most of the pages are written in [Markdown](http://daringfireball.net/projects/markdown/), which is a textual format for generating formatted text. 
Markdown syntax is very intuitive, you can get a quick review [here](https://help.github.com/articles/github-flavored-markdown/) or
Michael Kohlhase's avatar
Michael Kohlhase committed
60 61
[here](http://kramdown.gettalong.org/syntax.html).

Tom Wiesing's avatar
Tom Wiesing committed
62 63
**CAVEATS:** The Markdown engine used by this site is [Kramdown](http://kramdown.gettalong.org/). 
Its syntax definitions are slightly different from [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/), thus the preview feature in GitHub might not render source as in the final result.
Michael Kohlhase's avatar
Michael Kohlhase committed
64

Tom Wiesing's avatar
Tom Wiesing committed
65
Other reasons why GitHub's preview may not correspond to the final results are:
Michael Kohlhase's avatar
Michael Kohlhase committed
66

Tom Wiesing's avatar
Tom Wiesing committed
67 68
- Use of [Liquid templates](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) in the source. 
- Use of special purpose markup, HTML, and scripts, such as mathematical excerpts written in [MathJax](http://mathjax.org/).
Michael Kohlhase's avatar
Michael Kohlhase committed
69

70 71 72
### Editing the menu

The menu of the page is defined in the ``_config.yml`` file. 
Tom Wiesing's avatar
Tom Wiesing committed
73 74 75
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. 
Tom Wiesing's avatar
Tom Wiesing committed
76
* `active` - URL to a folder under which the item should automatically be expanded (if applicable). 
Tom Wiesing's avatar
Tom Wiesing committed
77 78
* `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. 
79
* `external` - If set to `true`, assumes that `url` is external to the page. 
Tom Wiesing's avatar
Tom Wiesing committed
80 81 82
* `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. 
83

Tom Wiesing's avatar
Tom Wiesing committed
84
**Singular items** can be inserted as following:
85 86
```yaml
# A single link to the /news/ page. 
Tom Wiesing's avatar
Tom Wiesing committed
87
- menu_title: 'News'
88 89
  url: '/news/'
# An external link to the bibliography page
Tom Wiesing's avatar
Tom Wiesing committed
90 91
- menu_title: 'Bibliography'
  menu_external: true
92 93 94
  url: 'https://kwarc.github.io/bibs/'
```

Tom Wiesing's avatar
Tom Wiesing committed
95 96
**Submenus**. The menu allows (up to) one level of submenus. There are three such cases:

97
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. Items with the `hidden` key in frontmatter set to true are automatically excluded. 
Tom Wiesing's avatar
Tom Wiesing committed
98 99 100
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. 

Tom Wiesing's avatar
Tom Wiesing committed
101
Because submenus are not clickable, the `url` for submenus is ignored when building the menu. 
Tom Wiesing's avatar
Tom Wiesing committed
102
Furthermore, if these are mixed between folders and static items, the folders will always show first. 
Tom Wiesing's avatar
Tom Wiesing committed
103 104 105 106 107 108 109 110 111

```yaml
# A listing of the folder submenu
- menu_title: 'People'
  folder: '/people/'
# A submenu of university links
- menu_title: 'FAU links'
  items:
    - menu_title: 'Overview'
Tom Wiesing's avatar
Tom Wiesing committed
112
      external: true
Tom Wiesing's avatar
Tom Wiesing committed
113 114
      url: 'https://fau.de/'
    - menu_title: 'CS department'
Tom Wiesing's avatar
Tom Wiesing committed
115
      external: true
Tom Wiesing's avatar
Tom Wiesing committed
116 117
      url: 'https://cs.fau.de/'
```
118

Tom Wiesing's avatar
Tom Wiesing committed
119 120 121
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. 

122 123
Furthermore, a menu may have the `url` key. If it is given, upon clicking the menu item, the given (internal) url is opened instead of opening the menu. 

Michael Kohlhase's avatar
Michael Kohlhase committed
124 125
### Working locally

Tom Wiesing's avatar
Tom Wiesing committed
126 127
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.
Michael Kohlhase's avatar
Michael Kohlhase committed
128

Tom Wiesing's avatar
Tom Wiesing committed
129 130
All you need to work locally is a [Git client](http://git-scm.com/). 
[Clone the repository](https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork) and start coding right away.
Michael Kohlhase's avatar
Michael Kohlhase committed
131

Tom Wiesing's avatar
Tom Wiesing committed
132 133 134
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](https://help.github.com/articles/using-jekyll-with-pages/#installing-jekyll) on your machine. 
It is recommended to install the [GitHub pages gem](https://github.com/github/pages-gem) which provides you with the exact same versions used by GitHub to compile your site.
Michael Kohlhase's avatar
Michael Kohlhase committed
135 136 137 138

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

~~~
139 140
gem install bundler
bundle install
Michael Kohlhase's avatar
Michael Kohlhase committed
141 142
~~~

143
in the local clone of this repository. 
Michael Kohlhase's avatar
Michael Kohlhase committed
144

145
Note that you will need Ruby headers (`ruby-dev` package on Ubuntu) in order to compile C dependencies.
Michael Kohlhase's avatar
Michael Kohlhase committed
146

147
You can then run the development server by: 
Michael Kohlhase's avatar
Michael Kohlhase committed
148 149

~~~
150
bundle exec jekyll serve
Michael Kohlhase's avatar
Michael Kohlhase committed
151 152
~~~

Tom Wiesing's avatar
Tom Wiesing committed
153
Your site will be generated in a `_site` sub-directory, and served live at <http://localhost:4000/>. 
Michael Kohlhase's avatar
Michael Kohlhase committed
154 155

Have fun!