README.md 3.48 KB
Newer Older
Michael Kohlhase's avatar
howto  
Michael Kohlhase committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
# The Sources of the SIGMathLing Web site

This is patterned after the [OpenDreamKit site](http://opendreamkit.org), also see the
README there. 

## About

This website is hosted as a [GitLab page](https://docs.gitlab.com/ee/user/project/pages/).
In short, 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 side bar. See the above links for details.

- `_config.yml`: main configuration page
- `_post/*.md`: sources of the news and blog posts
- `_layouts/*`: local style files
- `_includes/*`: reusable chunks of web pages, like the side bar
- `public/*`: Jekyll style files (almost vanilla), logos, ...

## How to use Jekyll to test/build this website

This is a
[*static website*](http://en.wikipedia.org/wiki/Static_web_page)
automatically generated with [Jekyll](http://jekyllrb.com/).

These instructions are for SIGMathLing members 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
sidebar. Alternatively, you can directly navigate to the corresponding
`.md` (Markdown) file in GitHub.

This will drop you in GitLab'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](https://help.github.com/articles/what-are-the-different-access-permissions/)
to the repository (hint: you do), your modifications will be published
right away.  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
[here](http://kramdown.gettalong.org/syntax.html).

### 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](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

~~~
69 70
gem install bundler
bundle install
Michael Kohlhase's avatar
howto  
Michael Kohlhase committed
71 72
~~~

73
in the local clone of this repository. 
Michael Kohlhase's avatar
howto  
Michael Kohlhase committed
74

75 76
 Note that you will need Ruby headers (`ruby-dev` package on Ubuntu) in
order to compile C dependencies. On OS X, just prefix these lines by a sudo.
Michael Kohlhase's avatar
howto  
Michael Kohlhase committed
77 78 79 80 81

Now you can `cd` into your local clone of the repository and launch
the compilation by

~~~
82
bundle exec jekyll serve
Michael Kohlhase's avatar
howto  
Michael Kohlhase committed
83 84 85 86 87 88 89
~~~

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!

Have fun!
90