Newer
Older
# Repository holding the sources of the KWARC.info website
<b>
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](http://rhodesmill.org/brandon/2012/one-sentence-per-line/).
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.
* `_config.yml`: main configuration page
* `_post/*.md`: sources of the news, blog posts and activities
* `_data/*.yml`: YAML database from which certain pages are automatically generated
* `_layouts/*`: local style files
* `_includes/*`: reusable chunks of web pages, like the nav bar
* `public/*`: all static files (images, js, css, etc)
* `project/` -- people -- event_activites: folders used to generate menu pages (as set in `_config.yml`)
* `_tagpages` : the tag pages, each tag gets an almost empty md file so that the tag page gets generated by jekyll
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/).
### 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](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
**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.
Other reasons why GitHub's preview may not correspond to the final results are:
- 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/).
### Editing the menu
The menu of the page is defined in the ``_config.yml`` file.
It contains three kinds of items:
1. **Folder menu**. An expandable sub-menu that contains all pages in a specific folder.
2. **Internal links**. A single link to a specific page.
3. **External links**. A link to an external page that automatically opens in a new tab.
The items can be defined by inserting them into the appropriate place in the list of menu items.
They look like
```yaml
# A folder menu for the /people/ folder
- title: 'People'
folder: 'people'
# A single link to the /news/ page.
- title: 'News'
url: '/news/'
# An external link to the bibliography page
- title: 'Bibliography'
external: true
url: 'https://kwarc.github.io/bibs/'
```
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](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.
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.
If you already have Ruby, the install part should be as easy as
~~~
gem install github-pages -V
~~~
Note that you will need Ruby headers (`ruby-dev` package on Ubuntu) in order to compile C dependencies.
On OS X, you can just type `sudo gem install github-pages -V`.
Now you can `cd` into your local clone of the repository and launch the compilation by
Your site will be generated in a `_site` sub-directory, and served live at <http://localhost:4000/>.
Any changes to the sources will trigger an automatic recompilation!