incubator-jena-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ian Dickinson <>
Subject Web site how-to
Date Tue, 04 Oct 2011 08:52:15 GMT
A quick recap on how to update documentation on the web site:

The site is generated by the Apache CMS, a home-grown content generation 
system based on Perl and markdown. General info and instructions on the 
CMS here:

However, the documentation isn't great. The salient points are:

* The source is Markdown, with a few extensions (tables, etc). There is 
one non-standard feature: the document needs to start with a Title 
element, which is used to generate an h1 at the top of the page (i.e. so 
you don't need an initial '# This is my page')

* All the source is in svn at:

* you can svn co that URL to get a local working copy of the site. When 
you commit, buildbot will notice and automatically run the conversion 
scripts to turn the markdown into html on the staging site:

* For major editing, I've found working on a local copy is easiest. For 
more lightweight editing, there is a link to go direct to a 'working 
copy' model in which you can edit wiki-like in the browser. See 'get 
Jena working copy' on:

You can also activate this mode via a bookmarklet; there are 
instructions on that page.

* To publish the external site from staging, use this link (which is 
also available from the page):

This will require one more commit (and log message), and will trigger 
buildbot to copy staging to external.

* Markdown is pretty straightforward, and has all of HTML as a subset. 
This means that taking files from the old site and dropping them into 
the CMS site sort-of 'just works'. You'll need to strip off some chrome 
(css links, etc), and adjust links.

* I've had pretty good success with using pandoc to auto-convert html to 
markdown. The only thing it fails on is tables, since these are not part 
of standard markdown. I've manually edited the files I've converted to 
put the markdown table syntax back in. Enterprising perl programmers may 
be able to automate this process, but I'm not sure it's worth the candle.

* The CMS should support the markdown ToC plugin, but it's borked. I 
have a JIRA bugrep in, but it has received no love from Infra as yet. I 
don't know who, if anyone, is maintaining the CMS code (and I fear to 
ask too stridently for fear of accidentally volunteering :)

* When doing major edits, it's possible to run the CMS scripts locally 
(so you can preview without going via staging). Bit of a pain to set up, 
but when it's working it does seem reliable - at least on Linux. I have 
no idea if it's easy, or even possible, on Windows.

I'll carry on with some of my general gardening and migrating content, 
but please feel free to start adding and editing content. Shout if you 
need any help.


View raw message