DHQ Static Site Generation

DHQ’s static site processes are driven by the build tool Apache Ant. When you run Ant, it will look for a build.xml file in your current directory, and use the “targets” defined in that file to execute a series of tasks. DHQ’s build file can be found in the main directory of the repository, along with the modifiable properties defined by DHQ.

Page contents

1. Installing Ant
2. Using Ant for DHQ
   1. Running Ant from the command line
      1. Ant with Saxon for XSL transformations
      2. Setting property values ahead of time
   2. Running Ant from oXygen
      1. Importing the oXygen scenarios
      2. Selecting an Ant scenario
      3. Re-running a scenario
3. Build targets
   1. Getting an article preview
   2. Generating a static copy of the DHQ site
   3. Making a proofing copy of unpublished DHQ articles

Installing Ant

In order to run an Ant build, you will first need to have Ant installed. If you only plan to run Ant through the oXygen editor, you don’t have to do anything special — oXygen comes bundled with Ant and will be able to process your build file without any additional installation from you. If you plan to run Ant through the Terminal (command line), however, please keep reading.

You should check to see if you already have Ant installed by running ant -version from your Terminal. If Ant is installed, you should see a message that includes the version number and compilation date of your copy of Ant. If Ant is not installed, the Terminal will report that the command was not found.

If you are on a Linux computer, you can likely install ant from your distribution’s package manager. If the ant package is not available, you may have to install Ant using one of the other methods described below.

If you are on a Mac or using Linux, you can obtain Ant through the Homebrew package manager. Once Homebrew is installed, you can run brew install ant from the command line.

To install Ant from a binary distribution, you can obtain a copy of the current release from the Ant Binary Distributions page. Then, follow the instructions in the “Installing Apache Ant” documentation.

Using Ant for DHQ

This is an overview on how to use Ant with DHQ’s build file. More specific use cases are covered in the “Build targets” section.

An Ant build file lists various <target>s, each of which represents a separate workflow you might employ. If you do not name the <target> you want to execute, Ant will run the target named in the default attribute on <project>, found at the top of the file.

In the DHQ’s build file, the default build target is previewArticle, which generates HTML for proofing an article.

Running Ant from the command line

First, navigate to your local copy of the DHQ repository, where build.xml lives. For example:

cd /Users/aclark/Documents/DHQ/dhq-journal

A basic Ant command looks like this:

ant [target]

You can either:

• omit [target] to run the default build target, previewArticle; or
• replace [target] with the name of the build target you would like to use instead.

For a list of DHQ’s <target>s, you can run ant help, or check out the descriptions in the “Build targets” section of this document.

Ant with Saxon for XSL transformations

Most of DHQ’s build targets require the XSLT processor Saxon HE. When you run Ant, you’ll probably need to tell Ant to load in the processor from DHQ’s common/lib directory. This is what an Ant command would look like in a Mac or Linux shell:

ant -lib common/lib [target]

On Windows, the command would look like this:

ant -lib common\lib [target]

The DHQ build file checks to make sure that Saxon is available before attempting to run any XSLT stylesheets. If you forget the -lib common/lib argument, don’t worry! Ant will put out a message describing the right command to use for your operating system.

Setting property values ahead of time

Some of DHQ’s build targets will ask you to define some value to be used in processing. By default, these targets will provide a prompt where you will type or paste in the value you want. However, you can also provide these values ahead of time using this format:

ant [-Dproperty=value] [target]

For example, the previewArticle target will default to asking you for the ID of the article you’d like to preview:

> ant -lib common/lib previewArticle

Buildfile: /Users/aclark/Documents/DHQ/dhq-journal/build.xml

previewArticle:

    [input] Please type the ID of the article you want to preview:

000668

If you want to quickly repeat the same transformation, you could instead provide the article ID as part of the command, e.g.:

ant -lib common/lib -Darticle.id=000668 previewArticle

Running Ant from oXygen

Currently, three transformation scenarios are available for oXygen:

• makeInternalPreview (See “Making a proofing copy of unpublished DHQ articles”)
• previewArticle and zipPreviewArticle (See “Getting an article preview”)

Importing the scenarios

Before you can run the Ant scenarios, you will first have to import them. To do so:

1. Click the "Options" menu.
2. Select "Import transformation scenarios..."
3. Navigate to the dhq-journal/ directory.
4. Click into the common/ directory.
5. Click into the xslt/ directory.
6. Select the file static-site.scenarios.
7. Hit the "Open" button.
8. Decide which scenarios you would like to import. (There is no harm in leaving them all selected.)
9. Optionally, select "Global Options" for storage. (If you make heavy use of oXygen's Projects feature, you may wish to use "Project Options" instead.)
10. Hit the "Import" button.

Once the scenarios are imported, you can use them while editing any file saved to the DHQ Journal repository.

Selecting an Ant scenario

To run an Ant build target, open the "Configure Transformation Scenarios" dialog box by clicking the wrench-with-a-play-button button in the toolbar, hitting Command Shift C (on a Mac), or hitting Control Shift C (on Windows). You can also get to this dialog by selecting the "Document" menu option, then "Transformations", then "Configure Transformation Scenarios".

Once in "Configure Transformation Scenarios", you can start typing "DHQ" into the search bar to narrow your options down to the scenarios you've just imported. Check the scenario you'd like to apply, then hit "Apply associated". Note that while it is possible to run multiple scenarios, it is not recommended to select multiple Ant targets here. Uncheck all but the one scenario you're most interested in.

When you hit "Apply associated", you will initiate an Ant build. Oxygen may prompt you for information (such as an article ID). It will then show you any Ant messages that appear during the transformation. Finally, when Ant is done, oXygen will open a file in your browser, allowing you to check the results.

Re-running a scenario

To re-run the same transformation while the same file is open, you can click the play button to "Apply transformation scenario(s)", hit Command Shift T (on a Mac), or Control Shift T (on Windows).

---

Build targets

DHQ’s build file contains these primary targets:

• help: Describe the Ant command format and the primary build targets in depth.
• previewArticle: Create an HTML preview version of a single article.
• zipPreviewArticle: Create a ZIP file which contains the HTML preview for a single article, as well as the site and article assets (CSS, JS, images).
• makeInternalPreview: Generate a proofing copy of the unpublished articles listed in the “editorial” section of toc.xml, and possibly the rest of the DHQ site.
• generateIssues: Generate static HTML versions of the DHQ issues and their articles, using XSLT on toc.xml.
• generateSite: Run generateIssues, then generate a full static copy of DHQ intended for the DHQ server.
• compressStatic: Compress the static copy of DHQ into a ZIP file.

The default target is previewArticle.

Excepting help and compressStatic, each of the above targets relies on XSLT processing. They require the Saxon processor and its dependencies to be on the classpath when Ant is called. If these resources are missing, Ant will stop and provide instructions for running the build with Saxon.

Getting an article preview

You can generate an HTML version of a specific article with the previewArticle and zipPreviewArticle targets.

Both of these targets require you to provide a six-digit ID for the article you want to preview. If you are using the command line, you can let Ant prompt you for this ID, or you can set the property article.id as part of your Ant command.

The previewArticle target assumes that you are proofing locally. When you run this build, Ant will create a directory called “dhq-preview” inside your copy of the DHQ repository. An HTML representation of the article will be stored there. When you open the HTML in your browser, you should be able to see the article displayed as if it was part of the DHQ website.

The zipPreviewArticle target is very similar in that it also stores HTML into the dhq-preview directory. However, Ant will also create a ZIP file containing this HTML and all of the CSS, Javascript, and images necessary to view the article on its own, without the surrounding DHQ architecture. Note that the HTML file inside dhq-preview will look broken when viewed in a browser. To fully preview the article from your own browser, you should either extract the contents of the ZIP file, or use the previewArticle target to replace the HTML file with a working version.

Generating a static copy of the DHQ site

The generateIssues and generateSite build targets work together to generate a full, static copy of the DHQ website. As part of these targets, Ant sets up a new directory “dhq-static” next to the dhq-journal repository. By the end of the process, the new folder will contain a full copy of the DHQ website at dhq-static/dhq/.

It is worth mentioning that this static version of the site is not a standalone version of the site. Every page depends upon CSS and Javascript assets served from /dhq/, and as such, the static site can only be fully proofed when stored on a server in the dhq directory, e.g. http://digitalhumanities.org/dhq/. This is a known weakness in the static site building process, and one we hope to fix soon.

Since generateSite runs the generateIssues target, you will likely find that running generateSite alone will serve your needs. You may wish to run generateIssues on its own in order to test changes to the XSLT stylesheets, however.

The full static site generation process (generateSite) looks like this:

1. Run the generateIssues target, which:
   1. creates a dhq-static directory next to the journal repository;
   2. generates issue indexes, contributor bios, and article HTML in the expected dhq/vol/#/#/ directory structure in the static directory; and
   3. generates a map of files from an article’s resources in the articles directory, to be copied to the appropriate dhq/vol/#/#/###### directory within the DHQ site hierarchy.
2. Run the generateSite target, which:
   1. copies article resources into the expected dhq/vol/#/#/###### directories;
   2. copies submissions text files and most web assets (excluding lib and tests);
   3. generates full HTML pages from the snippets in the about, contact, news, people, and submissions folders; and
   4. zips up all article XML to be served out of the data folder.

This build target does not compress the full website into a ZIP file. However, if you would like to make a backup, you can do this manually by running:

ant compressStatic

The resulting ZIP file will appear in the dhq-static directory.

Making a proofing copy of unpublished DHQ articles

The makeInternalPreview build target generates a web version of as-yet-unpublished DHQ articles for proofing by DHQ editors and authors. When you run this build, Ant will prompt you to decide whether or not to include the whole DHQ site in the proofing copy:

> ant makeInternalPreview  
Buildfile: /Users/aclark/Documents/DHQ/dhq-journal/build.xml

makeInternalPreview:
    [input] Do you want to proof the full DHQ site? If so, type "true".
    [input] To proof only the internal preview, hit the return key or type "false". (true, [false])

If you are using the command line, you can set the property do.proofing.full as part of your Ant command.

The proofing copy will be available in the “dhq-static” directory, created next to the dhq-journal repository. Whichever portions of the DHQ site you requested will be available in the dhq-static/dhq-preview/ folder.

Under the hood, this build target calls either generateIssues or generateSite, depending on how much of the site is included in the preview. As such, the HTML output has all of the same limitations of those targets. Namely, links to other pages may not work unless placed on a server.