Repository holding the sources of the OpenDreamKit.org website (aka OpenDreamKit.github.io)
This website is hosted as a github page. In short, 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 side bar. 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)
- publlic/reveal.js: local clone of reveal.js for slides support; you need to issue
git submodule initfollowed up by
git submodule updateto get it installed locally and view local copies of the pages using jekyll.
- project -- people -- events: 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
- meetings: our meeting content and pages, is accessible though not directely linked from anywhere on the site
See also the general help document for OpenDreamKit participants.
How to use Jekyll to test/build this website
These instructions are for OpenDreamKit participants who wish to do more than the occasional editing.
Editing pages online with GitHub
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 a short 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.
CAVEATS: The Markdown engine used by this site is Kramdown. Its syntax definitions are slightly different form 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. This is seldom used, but some pages (like the calendar) use them to access site-wide configuration variables.
- Use of special purpose markup, HTML, and scripts, such as mathematical excerpts written in MathJax.
The calendar page uses the yml file _data/events.yml to generate the calendar and the list of events. This is also used calendar.ics for the ICAL link.
The partners page uses the yml file _data/partners.yml to geneate the list of partners and institutions.
This is generated with the posts from the _posts folders. The tag system associates the tags written in each post to a tagpage in the _tagpages folder.
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.
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
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
bundle exec jekyll serve --incremental -w -b ''
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!