How to Publish a FHIR Implementation Guide
1.1.0 - release International flag

This page is part of the How to Publish a FHIR Implementation Guide (v1.1.0: Release) based on FHIR (HL7® FHIR® Standard) R4. This is the current published version. For a full list of available versions, see the Directory of published versions

Setting up the Publication Environment

Before using IG Publisher to publish your implementation guides, you need to set up a local environment to stage your IGs for publication. This is a single workspace that will be used for all releases of all implementation guides published to your website.

  1. Clone the HL7 history, web templates, and FHIR IG registry repositories. You'll need to commit changes to the ig-registry repo, so you may need to fork the repo if you have insufficient privileges.

    $ cd ~/src
$ git clone git@github.com:HL7/fhir-ig-history-template.git ig-history
$ git clone git@github.com:HL7/fhir-web-templates.git fhir-web-templates
$ git clone git@github.com:FHIR/ig-registry.git ig-registry

  2. Create a publication directory.

    $ cd ~/src
$ mkdir publication

    Alternatively you may want to create a publication repository to keep a copy of your website.

  3. Within the publication directory, set up the publication resources.

    $ cd publication
$ mkdir templates webroot
$ cp ../fhir-web-templates/*template* templates

    This creates a webroot directory, creates a templates directory, and populates it with the customizable portion of the history templates.

    You may now delete the fhir-web-templates repo.

    $ cd ~/src
$ rm -rf fhir-web-templates

  4. Edit the files in publication/templates to reflect the styling used across your site's IGs. This styling will be applied to the IG history pages and other content generated by the publication process. (Styling for your IG itself is determined by the IG's configured template.) Modify the templates to specify:

    • The correct favicon and CSS style sheets
    • Organizational logos or text in the page header
    • The copyright statement to display

    Supporting files should be added to webroot/assets-hist.

  5. In the publication directory, create the publication configuration file webroot/publish-setup.json, updating fields as appropriate for your site.

    {
   "website": {
      "style": "fhir.layout",
      "url": "http://example.org/ig",
      "server": "apache",
      "org": "Example Organization",
      "search-template": "searchform.template.html",
      "index-template": "index.template",
      "clone-xml-json": true
   },
   "feeds": {
      "package": "package-feed.xml",
      "publication": "publication-feed.xml"
   },
   "layout-rules": [
      {
         "npm": "org.example.*",
         "canonical": "http://example.org/ig/{3}",
         "destination": "/{3}"
      }
   ]
}

    This file defines the structure of your publication site, and where certain files are found.

    • url is the base url of the web site
    • server is one of the supported webserver types: apache (apache or nginx), cloud (S3, etc. or GitHub pages) asp-old, asp-new. This is used to determine how to construct redirects.
    • org is your organization name
    • clone-xml-json determines whether the redirects to handle Accept headers of, for example, application/json, application/fhir+json and application/json+fhir require distinct copies of the target file (when true) or whether all of those content types can be supported with a single file (when false).
    • layout-rules specify how IGs are published under the site. You may specify entries for specific IGs, or patterns that your IGs follow:
      • npm is the package id, or pattern (with wildcards) of package ids, that this layout rules applies to. The package id is made up of period-separated components.
      • canonical is the canonical URL of IGs following this layout rule. It is either fully specified, or describes how to create canonical URLs from the package id components. This example shows a canonical generated using the third component of the package id.
      • destination is the location under the webroot directory to stage your IG before uploading. This usually agrees with the information in canonical.

  6. Create webroot/publication-feed.xml, updating fields as appropriate for your publication.

    <?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:dc="http://purl.org/dc/elements/1.1/"
      xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:fhir="http://hl7.org/fhir/feed"
      xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
   <channel>
      <title>Example Organization FHIR Implementation Guides</title>
      <description>FHIR Implementation Guides published by Example Organization</description>
      <link>http://example.org/ig</link>
      <generator>Example Organization</generator>
      <lastBuildDate>Thu, 23 Mar 2023 12:00:00 GMT</lastBuildDate>
      <atom:link href="http://example.org/ig/publication-feed.xml" rel="self" type="application/rss+xml" />
      <pubDate>Thu, 23 Mar 2023 12:00:00 GMT</pubDate>
      <language>en</language>
      <ttl>600</ttl>
      <item>
      </item>
   </channel>
</rss>

    This defines the RSS feed used by the FHIR registry to find all the versions of all the implementation guides published on your site.

  7. Copy webroot/publication-feed.xml to webroot/package-feed.xml, and:

    • Update file name in the <atom:link> element
    • Update the description and title as appropriate for "packages" rather than "guides"

    This file defines the RSS feed used by the FHIR registry to find the packages for the implementation guides published on your site.

  8. Download the latest HL7 IG Publisher to a convenient location.

    $ curl -L https://github.com/HL7/fhir-ig-publisher/releases/latest/download/publisher.jar -o ~/src/publisher.jar

  9. From the publication directory, generate webroot/package-registry.json:

    $ cd ~/src/publisher
$ java -jar ../publisher.jar -generate-package-registry webroot

  10. In the ig-registry repo, create a branch for your changes.

    $ cd ~/src/ig-registry
$ git checkout -b example-org-igs

  11. Update package-feeds.xml, so that the registry will know about your packages. Add your feed to the feeds array:

    {
  "comment" : "The order of the feeds does not matter, but the order of the package-restrictions does",
  "feeds": [
     ...
     {
        "name": "Example Organization FHIR Implementation Guides",
        "url": "http://example.org/ig/package-feed.xml",
        "errors": "admin|example_org"
     }
  ],
  "package-restrictions": [
     ...
  ]
}

    The errors element contains the contact email for this feed, replacing @ and . with | and _.

Your publication workspace is now prepared. If appropriate, you may want to commit the publication directory repository.

To publish an actual IG, proceed to Using IG Publisher -go-publish.