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

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