Building the site

In brief: the documents in the src directory are transformed into HTML (as appropriate) and the resulting HTML documents are stored in the build directory. After the transformations are complete, the contents of the build directory is published as markupdeclaration.org.

The sources

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.

Build process

The build system runs on the JVM and is based on Gradle. It uses a number of additional technologies, but these should be transparent to users who simply wish to edit pages.

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:

1. Clone the repository. This will make a copy of it on your computer.
2. Open a shell window of some sort (on Windows, a command or PowerShell window should be fine).
3. Navigate to the directory where you cloned the repository.
4. Run the command “./gradlew”

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.

The gradlew command will run, producing a variety of status messages as it goesl. 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.

Other files

In addition to transforming the source documents, the build script copies the css and img directories to the build directory.

Metadata and navigation

In addition to formatting each page, the build script tinkers with the head, header, and 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 the 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 appropriate directory.

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 pubmeta:

• head names the head template.
• header names the header template.
• footer names the footer template.
• title provides an override title for the document.
• date provides an override publication date.

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 git log.

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.