Apache JSPWiki website
(adapted from Apache Guacamole site)
Most of this website is powered by Apache JSPWiki itself, under http://jspwiki-wiki.apache.org
This website itself is completely static, being automatically generated by JBake prior to deployment. The content of the website is written in a mixture of Freemarker templates and Markdown. Templated content is interpreted only at build time, with the final result being completely static. This allows us to have a fast, backup site if needed, and also to publish our apidocs easily (see publishing apidocs below).
To facilitate ease of development and testing, this repository also contains a couple of build scripts,
mvn-ci.sh, the usage of which is documented below.
Table of contents
In addition to the
NOTICE files required of any proper Apache-licensed project, the repository contains the following critical files:
./pom.xml: orchestrates the maven website build
./ci.sh: script, meant to be run by a CI server, to build and deploy the website.
./mvn-ci.sh: script to build and deploy the website using Maven.
./src/main/jbake/: standard jbake maven plugin structure, contains three subdirectories:
./src/main/jbake/content/: holds content files, with the extension of these files determining what type of content it contains (i.e.:
.htmlfor raw HTML, etc.).
./src/main/jbake/templates/: holds templates files, with the extension of these files determining the templates engine (i.e.:
.thymefor Thymeleaf, etc.).
./content/: the actual content served for jspwiki.apache.org, see publishing changes below.
The CI build (
ci.sh) needs Java 7 and a JBake installation under
$JBAKE_HOME. This script is run at ASF's Jenkins instance. As there isn't a Maven installation at the nodes which perform this job, this script only takes the changes from the "jbake" branch, generates the site and puts it on the "asf-site" branch. As for now, javadocs must be pushed locally through the Maven build script.
The Maven build (
mvn-ci.sh) needs at least Maven 3.1.1 and Java 7, thus these must be installed first. It's essentially the same build as the CI build, but done through Maven. This allows us to generate the site and also put the javadocs in there.
mvn clean jbake:inline and the site will be accesible through http://localhost:8080. Changes will be reloaded on the fly. When done testing your local changes, press
Enter to stop the web server and return to the shell.
In order to be able to navigate locally, you'll need to edit the
site.host property at
Do NOT commit that change.
Changes to the website are published using Apache's gitpubsub which relies on a special branch called "asf-site" containing all website content.
In the Apache JSPWiki website repository, the "asf-site" branch is an "orphan" branch. Updating the website thus involves:
- Making and testing your changes locally
- Replacing the entire contents within "asf-site" with the newly-generated site from the "jbake" branch.
Second step is automated through
Keep in mind that the new content must be staged for and committed in this branch. Once you have verified that the staged content is as expected, commit your changes (along with a useful commit message describing the changes at a high level) using
git commit and publish the update using
git push origin.
If you wish to unstage your changes, use
git reset --hard HEAD to return to the original state of "jbake", wiping out any local modifications. You can then return to whichever branch you were working on with
mvn-ci.sh script locally. This will generate the whole site with the javadocs, and push it to the
asf-site branch. As for today, this has to be done locally, as the Jenkins' nodes which build and deploy the site don't have a Maven installation.