Introduction

The Gradle Site Plugin came about as the result of doing a collection of Gradle tasks repeatedly across multiple projects. Each time I would copy and paste the collection of task definitions from one project to another, I cringed and told myself that I would sit down and pull them out into a plugin. Finally, that day has come. My goal with this plugin is to provide and mostly-generic means of creating a documentation web site for a project. I have tried to keep things very light and convention-based so that things just work, especially around the inclusion of API documentation and build reports.

That being said, what this plugin does not provide is a set of site templates; however, I am considering that as a possibility for a later release. I decided that I would rather not directly promote the white-washed project site problem where they all start to look alike - this at least encourages some though about the look of the landing page; come on, it’s one page of HTML, give it a try.

Configuration

Most of the configuration for the Site Plugin is done with the site DSL extension; however, there is some additional functionality added when certain other plugins are applied.

Site Extension

Ths site DSL extension is the primary means of configuring the Site Plugin; it’s properties and methods are described below.

Properties

  • String srcDir - configures the source directory for the project site content (defaults to src/site).

  • String buildDir - configures the build directory for the generated and aggregated project site content (defaults to build/site).

  • String siteUrl - an optional configuration used to specify the production project site URL, used by verifySite as the default site URL.

  • List<String> testedPaths - configures the additional paths to be checked during the verifySite execution

  • List<String> versionedFiles - configures the additional files noted as having version information to be updated during updateVersion execution.

  • 'Map<String,Object> variables` - configures the additional site content replacement variables.

Methods

  • testedPath(String) - adds a path to those checked during the verifySite execution.

  • versionedFile(String) - adds a file noted as containing version information which should be updated during an updateVersion execution.

  • variable(String, Object) - add the specified site content replacement variable.

  • variables(Map<String,Object>) - adds all of the provided site content replacement variables.

Web Preview Plugin

If you have my Web Preview Plugin applied to your build, the Site Plugin will configure the preview to serve the generated project site by applying the following configuration:

webPreview {
    resourceDir = site.buildDir
}

This allows addition of local site previews on an embedded server with only the application of the plugin:

./gradlew startPreview

More usage details can be found on the Web Preview Plugin web site.

Task Dependencies

It is advisable to simplify your site builds by adding your documentation tasks as dependencies of the site task. In your build.gradle file you can add something like the following, with your own documentation and report tasks:

tasks.site.dependsOn = ['build', 'jacocoTestReport', 'groovydoc', 'asciidoctor']

This causes the site task to build the project with reports and documentation by simply running:

./gradlew site

which keeps you from having to remember all of the dependency tasks.

Tasks

site

The site task is used to build the project site. The generated project web site is an aggregation of any content in your site srcDir, the content from any generated reports (build/reports), the content from any generated API documentation (build/docs), and the content from an AsciiDoc user guide ('build/asciidoc`), if there is one. The contents of these directories are copied into the site buildDir location.

Any HTML files in the site srcDir will be processed with some replacement variables (as Groovy templates). The provided variable replacements are:

  • project_version - the string representation of the current version for the project (from the build.gradle file configuration).

  • year - the current year.

Other replacement variables may be configured in the site DSL extension with the variables property, or the variable(String) or variables(Map<String,Object>) methods.

Also, note that since these files are treated as Groovy templates you will have other Groovy functionality available for use.

The directories css, js, img will also have their content copied into the site build directory under the appropriate directories. Other directories may be added using the List<String> assetDirs property or the assetDir(String) method - these specified site source sub-directories (with optional ant pattern) will be copied over to the build directory un-processed. For example:

site {
    assetDir '**/fonts/**'
}

This would copy over the fonts sub-directory and its contents to the same sub-directory under the site build directory.

checkVersion

The checkVersion task is used to verify that all of the "versioned" files have the correct version as expressed by the build.gradle file. By default, only the README.md file is checked (if one exists); however, additional files may be specified in the site DSL extension using the List<String> versionedFiles property or the versionedFile(String) method.

The check is done with a simple verification that the version string exists within the file content - it’s not foolproof but better than nothing.

updateVersion

The updateVersion task is used with a CLI input parameter -Pfrom=VERSION where VERSION is the old version of the project (before the build.gradle version was updated). Running this task will do a string replacement of the old version string with the current version string in all of the configured "versioned" files. By default, only the README.md file is versioned (if one exists); however, additional files may be specified in the site DSL extension using the List<String> versionedFiles property or the versionedFile(String) method.

The check is done with a simple verification that the version string exists within the file content - it’s not foolproof but better than nothing.

verifySite

The verifySite task is used to verify the published site contents. By default, the siteUrl configured in the site DSL extension is used as the published site URL; however, this may be overridden on the command line using -PsiteUrl=SITE_URL.

By default, only the index.html page is verified. Other pages may be added using the List<String> testedPaths property or the testedPath(String) method of the site DSL extension.

This task only checks for the existence of the specified pages, not their content.

Publishing

The Site plugin provides no direct means of publishing the project site, nor does it require any specific publication environment; however, if you are using GitHub to host your project repository, you can use the GitHub-Pages functionality to host the project web site.

Create an empty gh-pages branch in your repo, then in your development branch create a publish.gradle file in the root of your project with the following content:

publish.gradle
plugins {
    id "org.ajoberstar.github-pages" version "1.5.1"
}

githubPages {
    repoUri = GIT_CLONE_URI
    pages {
        from(file('build/site')) {
            into '.'
        }
    }
}

replacing GIT_CLONE_URI is the URL used to clone your repo.

Then, add the following to the bottom of your main build.gradle file:

task publishSite(type: GradleBuild, group: 'Publishing', description: 'Publishes the documentation web site.', dependsOn: ['site']) {
    buildFile = 'publish.gradle'
    tasks = ['publishGhPages']
}

These modification provide a simple means of publishing the rendered site content to the gh-pages branch of your project, which GitHub will pick up by default and use as your project web site.

Tip
 You can read more about this functionality by reading Configuring a Publishing Source for GitHub Pages.

Eating My Own Dog Food

Since this plugin was created to replace duplication in my own code, it is one that I use in most of my projects, including this one. It makes for an interesting integration test when you release a project and then use it for its own site generation…​ keeps you honest.

Likewise, using the plugin for this project, means that this project is a good example of how it may be used as well as some ideas about the site landing page content itself (index.html page).