Michael Kohlhase committed Apr 30, 2017 1 2 # Repository holding the sources of the KWARC.info website  Tom Wiesing committed May 07, 2017 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 committed May 07, 2017 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 committed Apr 30, 2017 9   Tom Wiesing committed May 07, 2017 10 ## About  Michael Kohlhase committed Apr 30, 2017 11   Tom Wiesing committed May 07, 2017 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 committed Apr 30, 2017 16   Tom Wiesing committed May 07, 2017 17 * _config.yml: main configuration page  Michael Kohlhase committed Jun 13, 2017 18 * _includes/*: reusable chunks of web pages, like the nav bar  Tom Wiesing committed May 07, 2017 19 * _layouts/*: local style files  Michael Kohlhase committed Jun 13, 2017 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 committed May 07, 2017 24 * public/*: all static files (images, js, css, etc)  Michael Kohlhase committed Jun 13, 2017 25 26 * public/*.md: descriptions of the research areas * systems/*.md: descriptions of the KWARC sytems  Tom Wiesing committed Jun 23, 2017 27 * courses/*.md: KWARC courses (this may be obsoleted by univis)  Michael Kohlhase committed Apr 30, 2017 28   Tom Wiesing committed Jun 05, 2017 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 committed Aug 25, 2017 36 37  * unneeded iterations  Michael Kohlhase committed Aug 25, 2017 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 ifs instead of a single and * unneeded variable assignments (these seem to take a lot of time in liquid)  Tom Wiesing committed Jun 05, 2017 44   Michael Kohlhase committed Apr 30, 2017 45 46 ## How to use Jekyll to test/build this website  Tom Wiesing committed May 07, 2017 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 committed Apr 30, 2017 48   Tom Wiesing committed May 18, 2017 49 ### Editing pages online with GitHub / GitLab  Michael Kohlhase committed Apr 30, 2017 50   Tom Wiesing committed May 07, 2017 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 committed Apr 30, 2017 60 61 [here](http://kramdown.gettalong.org/syntax.html).  Tom Wiesing committed May 07, 2017 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 committed Apr 30, 2017 64   Tom Wiesing committed May 07, 2017 65 Other reasons why GitHub's preview may not correspond to the final results are:  Michael Kohlhase committed Apr 30, 2017 66   Tom Wiesing committed May 07, 2017 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 committed Apr 30, 2017 69   Tom Wiesing committed May 18, 2017 70 71 72 ### Editing the menu The menu of the page is defined in the _config.yml file.  Tom Wiesing committed May 18, 2017 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 committed Jun 23, 2017 76 * active - URL to a folder under which the item should automatically be expanded (if applicable).  Tom Wiesing committed May 18, 2017 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.  Tom Wiesing committed Jun 06, 2017 79 * external - If set to true, assumes that url is external to the page.  Tom Wiesing committed May 18, 2017 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.  Tom Wiesing committed May 18, 2017 83   Tom Wiesing committed May 18, 2017 84 **Singular items** can be inserted as following:  Tom Wiesing committed May 18, 2017 85 86 yaml # A single link to the /news/ page.  Tom Wiesing committed May 18, 2017 87 - menu_title: 'News'  Tom Wiesing committed May 18, 2017 88 89  url: '/news/' # An external link to the bibliography page  Tom Wiesing committed May 18, 2017 90 91 - menu_title: 'Bibliography' menu_external: true  Tom Wiesing committed May 18, 2017 92 93 94  url: 'https://kwarc.github.io/bibs/'   Tom Wiesing committed May 18, 2017 95 96 **Submenus**. The menu allows (up to) one level of submenus. There are three such cases:  Tom Wiesing committed Oct 15, 2017 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 committed May 18, 2017 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 committed Jun 23, 2017 101 Because submenus are not clickable, the url for submenus is ignored when building the menu.  Tom Wiesing committed Jun 05, 2017 102 Furthermore, if these are mixed between folders and static items, the folders will always show first.  Tom Wiesing committed May 18, 2017 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 committed Jun 05, 2017 112  external: true  Tom Wiesing committed May 18, 2017 113 114  url: 'https://fau.de/' - menu_title: 'CS department'  Tom Wiesing committed Jun 05, 2017 115  external: true  Tom Wiesing committed May 18, 2017 116 117  url: 'https://cs.fau.de/'   Tom Wiesing committed May 18, 2017 118   Tom Wiesing committed Jun 23, 2017 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.  Tom Wiesing committed Oct 15, 2017 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 committed Apr 30, 2017 124 125 ### Working locally  Tom Wiesing committed May 07, 2017 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 committed Apr 30, 2017 128   Tom Wiesing committed May 07, 2017 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 committed Apr 30, 2017 131   Tom Wiesing committed May 07, 2017 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 committed Apr 30, 2017 135 136 137 138  If you already have Ruby, the install part should be as easy as ~~~  Tom Wiesing committed Jun 06, 2017 139 140 gem install bundler bundle install  Michael Kohlhase committed Apr 30, 2017 141 142 ~~~  Tom Wiesing committed Jun 06, 2017 143 in the local clone of this repository.  Michael Kohlhase committed Apr 30, 2017 144   Tom Wiesing committed Jun 06, 2017 145 Note that you will need Ruby headers (ruby-dev package on Ubuntu) in order to compile C dependencies.  Michael Kohlhase committed Apr 30, 2017 146   Tom Wiesing committed Jun 06, 2017 147 You can then run the development server by:  Michael Kohlhase committed Apr 30, 2017 148 149  ~~~  Tom Wiesing committed Jun 06, 2017 150 bundle exec jekyll serve  Michael Kohlhase committed Apr 30, 2017 151 152 ~~~  Tom Wiesing committed May 07, 2017 153 Your site will be generated in a _site sub-directory, and served live at .  Michael Kohlhase committed Apr 30, 2017 154 155  Have fun!