-
Notifications
You must be signed in to change notification settings - Fork 6
Website tech howto
This is a bit of information about the www.aeolusproject.org website, intended for those who want to contribute.
Our website is hosted on GitHub Pages, and powered by jekyll. Most pages are written in Markdown.
To contribute, you can fork this repo, edit the appropriate files in your fork, commit them to a topic branch, and send a pull request. Those two linked pages will walk you through the process if you are new. (If you have found issues on our site but don't have the time or resources to send a pull request, please feel free to use the Issues tab above to file a bug against the site. Or nag us by one of the methods on our Contact page.)
In the simplest form, you are free to simply write Markdown, which should be perfectly valid.
In many cases, we want to do more, though—add a header, make sure we use the main layout, and maybe use some HTML for specifying things like divs for styling. Here's an example of that:
---
layout: page
title: Sample Page
---
{::options parse_block_html="true" /}
# A big heading
<div class="section-grouping">
## Image
Here is an image you might like. We want to explicitly set size attributes, which Markdown doesn't support:
<img src="/images/concept_aeolus_high_level.png" width="767" height="460" />
</div>
The oh-so-intuitive {::options parse_block_html="true" /} bit is needed only if you are embedding HTML within a Markdown page; if you have pure Markdown it is unneeded.
The <div class="section-grouping"> is a common part of our layout, giving us a background for content. Not all pages use it, but many do—either a series of them for blocks of content, or with the whole page in one. It does not appear possible to accomplish this in Markdown.
Note: The stylesheet is actually SASS. I've sent a pull request to rename it; this should get updated after that.
Our site's styles are defined in css/site-wide.scss. The SCSS is compiled to CSS, but not automatically by Jekyll.
If you update the styles, please change the SCSS, and then regenerate the CSS like so:
$ sass css/site-wide.sass css/site-wide.css
Then, check both files in.
(This information is actually in our README, but I'm duplicating it here.)
- Make sure you have the jekyll gem installed with
gem install jekyll - Start the server up with
jekyll --server --auto. (The--serveroption starts a webserver on localhost:4000. The--autooption will automatically regenerate when files are changed; handy if you leave this running while working.)