Building the site
In brief: the documents in the
src directory are transformed
into HTML (as appropriate) and the resulting HTML documents are stored
build directory. After the transformations are complete, the
contents of the
build directory is published as
If you look in the
src directory, you’ll find all of the pages that
appear on the website. The source pages are available in a mixture of
markup formats: Markdown (specifically, CommonMark),
XHTML, and (DocBook) XML.
The build system attempts to hide the complexities of website construction (CSS files, navigation elements, etc.). Each source document stands alone in its format.
If you wish to update a document, simply edit it. If you wish to create a new document, decide what format you prefer to use and add it. (If you want to author in a different XML vocabulary, plase open an issue requesting it.)
If you add a new directory, please name your document “index” or add an “index” document that points to it.
You don’t have to build the website locally in order to make a pull request, but you may want to because it will allow you to see your changes “in context”.
If you want to build the website locally, follow these steps:
- Clone the repository. This will make a copy of it on your computer.
- Open a shell window of some sort (on Windows, a command or PowerShell window should be fine).
- Navigate to the directory where you cloned the repository.
- Run the command “
The first time you run
gradlew, it will download all of the tools
that are needed to build the website. You’ll have to have an internet
connection for this part, but you don’t need it for subsequent builds.
gradlew command will run, producing a variety of status messages
as it goes. The final output should look something like this:
❯ ./gradlew > Task :website Built website BUILD SUCCESSFUL in 1s 11 actionable tasks: 11 executed
Now you can open “
build/index.html” in your favorite web browser.
Go forth and edit!
Behind the scenes
The explanation above elides a few details that are not supposed to be relevant in the normal case.
In addition to transforming the source documents, the build script copies the
Metadata and navigation
In addition to formatting each page, the build script tinkers with the
footer of each document. This is how CSS
links are added and consistent navigation is achieved.
The head, header, and footer contents are stored in directories under
include directory. These are the files that you have to change
if you want to update the style or navigation elements.
In the ordinary case, the
default.xml versions of head, header, and
footer are used. If you want a particular page to have a non-standard
version of one of these files, add the alternate version to the
Each of the markup formats can have a
<pubmeta> element. In
Markdown, this can occur anywhere, though the top of the file is
probably the best place (yes, in CommonMark it can appear as a little
XML island). In HTML, it should be in the documents
head. In other XML formats, it should be in an appropriate container
near the top of the document.
The following elements can occur in
headnames the head template.
headernames the header template.
footernames the footer template.
titleprovides an override title for the document.
dateprovides an override publication date.
The build scripts use the commit date of the source document to
determine the publiation date. In order to do this, the build system
has to run a Perl script to post-process the output from
That’s not especially portable, so it only runs on Travis. In your local build, all of the publication datess will be “today”. You can ignore this.
But what about...
If you're having trouble, are confused about the build, or think an additional feature would be useful, please open an issue.