[CCC DEV] WWW Infrastructure

Jon Simpson me at jonsimpson.co.uk
Sun Dec 4 01:23:26 GMT 2011


Hi Matt,

On 29 Oct 2011, at 14:45, Matt Jadud wrote:
> [Braindump coming... expect some disconnects from reality and extreme
> fantasy ahead... :D] ....


Thanks for taking the time to fully explore and expand these ideas in your previous e-mail. For others reading, I suggest re-reading Matt's e-mail if you're interested in the context and requirements - I won't attempt to paraphrase or quote, the substance of ideas would be the worse for it.

TLDR: I have completed a port of the website across to the Jekyll (http://jekyllrb.com/) static site generation engine, with the aim of enabling the site to be maintained in and served from Github Pages (http://pages.github.com/). This repository is at https://github.com/exo/ccc-pages/tree/gh-pages and web visible at http://ccc.jonsimpson.co.uk/ (CNAME record pointed to Github/pages served from Github) 

Detail:

# Jekyll

Apart from allowing us to use Github Pages, a benefit I'll come to seperately, Jekyll is a relatively popular static site generation engine written in Ruby. It's bundled as a gem, which allows single command install on OS X, is well documented [1] and has a decent amount of supporting information out there [2].

[1]: https://github.com/mojombo/jekyll/blob/master/README.textile
[2]: http://stackoverflow.com/search?q=jekyll

Generally, Jekyll lets us build a static copy of the website from the source directory, leaving a directory which can be placed on any webserver to make up the site - all processing is done ahead of time. Jekyll can be run in a local server mode, with auto rebuilding, to allow easy previewing of content and changes ahead of commit/generation.

When Christian wrote Licorice, we had talked about the mechanics of content management and Jekyll was something that influenced my thinking on the topic - you'll find that the layout, formatting and functioning of Jekyll is actually very similar to that of the existing site. Content is marked up using Markdown, and transformed using a selection of templates depending on specifications made in the preamble of the content file.

# Github Pages

Github Pages basically offers a hosted installation of Jekyll - on pushing to either a specific branch in a project (i.e. a concurrency.cc github project with a gh-pages branch), or a specifically named project (e.g. a concurrency.github.com repos in a github account named 'concurrency') github will automatically run Jekyll and make the output web-visible from Github's servers with no further intervention required.

This gives the ability to host the authoritative, live copy of the site in Github and push pages live to the web without any commit-hooks/file syncing from statically generated copies (basically, removing user visible moving parts).

Putting these two together gives us a user story for the website of cloning the repository (either via git command line, or github's UI), creating a weblog post, new page, or set of resources and then creating a pull request back to the source repository for review (content AND markup) and merging. 

Given that I've taken a quick skim over 100% of the marked up content that makes up the existing website, I think having an opportunity on that pull request to review the markup would help avoid the problems you outlined that grow when things are done ad-hoc without general visibility. (There's a combination of gaps in the existing stylesheets and the learning curve on Markdown's syntax that have sprung the existing awkwardness in some files)

Github pages can serve to an external domain, as demonstrated - I've configured the example to serve from a subdomain of my domain, rather than its original URL of http://exo.github.com/ccc-pages/  I've put a list of current FIXME's/TODO's in the repos README that are currently outstanding.

# Other things from the original e-mail

* Wiki (point 5 original e-mail) - We can use Github's wiki functionality alongside the main repository for this functionality, which is also exposed via git as plaintext in the repos

* Your book needs are a little harder to hit - I definitely agree that getting it into the repos/web visible at a source level would be great. Markdown isn't designed for entire documents, but MultiMarkdown (http://fletcherpenney.net/multimarkdown/) is, and is a possible option for such a thing. It supports HTML & LaTeX output natively - I'm generating a PhD Thesis from MMD source without *too* much trouble. [Disclaimer: I'm a big Markdown/MultiMarkdown fan, YMMV] I don't claim that it'll be effortless, but it can most likely be made to work if you think there's benefit to be collected from the effort to get going & set-up for your ways of working.

This ran too long. I'm putting this out there - All, push back please :)

Jon


More information about the developers mailing list