FHIR IG publisher templates

FHIR IG templates are used by the FHIR IG Publishing tool when publishing FHIR Implementation Guides. The templates control:

• the look and feel of the published IG
• the way the resources are expressed as pages
• how users navigate around the pages

From the point of view of an IG Author, the IG template consists of a list of files and documentation that describes how the author writes their own narrative and fits that into the pages described by the template.

Known IG templates

To use a template, you specify the 'template' parameter in the IG. You can nominate either the official code for a template (where it has one defined that is controlled by the FHIR product director), or the URL of the location of the template.

List of known IGs:

• "test" (http://gitub.com/fhir/test-template) - a test template the generates all the kinds of things that can be published
• "hl7" (http://gitub.com/hl7/fhir-ig-template - the standard template for HL7 published implementation guides
• "hl7-au" (http://gitub.com/hl7-au/fhir-ig-template - the standard template for HL7 Australia published implementation guides
• "ihe" (todo): the standard template for IHE-published implementation guides

note to template authors: you can add your template to this list, as a url + documentation, but only the FHIR product director can assign standard codes.

Authoring IG templates

The information below is for authors of templates and is highly technical. It should only be used by template authors.

A template contains 3 kinds of artifacts:

• configuration files that describe how resources are rendered into HTML
• active scripts that generate content as part of the build process
• jekyll templates / include files / html files

In addition to these artifacts which are for the IG publisher, the template must contain documentation that describes how an author adds pages and narrative content to the Implementation guide.

Template Resolution

When accessing a template by its URL:

• if the URL specifies a github.com location, then the IG publisher will assume that the template is a github repository and download it directly
• if the URL is a file location, then the IG publisher will assume that template is local, and copy all the files
• else it will look for [url]\package.tgz, or [url]\package.zip

When copying the files, all the files will be placed into a \template directory alongside the \temp directory, except for any files in a folder named "content" in the template, which will be copied into the \temp directory - e.g. provided to Jekyll as published content directly

File layout of a Template

The template lives in a github location somewhere. There are 2 important folders in the template layout:

• package - must contain a file package.json, with contents as below.
• template - contains the actual contents of the template that are distributed

Any other folders can exist and contain whatever the author wants- they are ignored by the FHIR IG publisher tooling.

The template folder has the following rules for it's content:

• it must contain a conf.json file - content see below
• anything in a "jekyll" folder gets passed straight through to Jekyll for generation - this is the core html / layout part of the template
• it can contain any other folders - these are available to the script events (see below) but not published

package.json

Use this as a template:

 {
  "name": "[package-id]",
  "version": "[ver]",
  "type": "fhir.template",
  "license": "[license]",
  "description": "[description]",
  "author": "[url]"
}

Notes:

• [package-id] must be chosen in association with the FHIR product director
• [ver] is under manual control of the author. Use semver
• [license] - license of author's choice. Use CC0-1.0 for HL7 published templates
• [description] - whatever
• [url] - your org/personal website. use http://hl7.org/fhir for HL7 authored templates

Configuration file

...to document... what goes in here:

• default templates and resources locations

Active Scripts

A template can contain 2 ant build scripts that allow the template to inspect the content of the IG and generate additional content. These will be run at selected points in the build process:

• before-generate.xml - run as soon as all the content is loaded and the resource outputs are generated, but before any html fragments are generated - this is provided so that the template can generate template-config.xml/json and/or to perform pre-processing on resource content (see below)
• after-generate.xml - run after all the generation is complete, before Jekyll is run: this the primary template active point to generate whatever additional content the template wants the output files/fragments to contain

The ant scripts can do whatever is desired, with the following limitations:

• The build file should be able to run offline (e.g. only depend on content in the template and from the IG publisher)
• whatever the script does should run ok on windows, linux, and OSX
• The IG auto-publisher will only accept templates that include active scripts if they are in the list of standard templates above.

Note: if you run the IGPublisher jar with the parameter -debug, it will stop and wait for a prompt at the script execution point to allow template authors to inspect the content of the temp folder

Jekyll template files

Any files in "content" will be passed through untouched to the Jekyll build directory