How to Publish a FHIR Implementation Guide
1.0.0-ci - ci-build
How to Publish a FHIR Implementation Guide
1.0.0-ci - ci-build
How to Publish a FHIR Implementation Guide, published by Argentix Informatics, Inc.. This guide is not an authorized publication; it is the continuous build for version 1.0.0-ci built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/ElliotSilver/how-to-publish/ and changes regularly. See the Directory of published versions
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.
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
Create a publication directory.
$ cd ~/src
$ mkdir publication
Alternatively you may want to create a publication repository to keep a copy of your website.
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, and puts a copy of the IG Publisher in the publication directory.
You may now delete the fhir-web-templates repo.
$ cd ~/src
$ rm -rf fhir-web-templates
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. Modify the templates to specify:
Supporting files should be added to webroot/assets-hist.
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"
},
"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 siteserver is one of the supported websever types: apache (apache or nginx), litespeed, asp-old, asp-neworg is your organization namelayout-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 url for the IG publication. This usually agrees with the information in canonical.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.
Copy webroot/publication-feed.xml to webroot/package-feed.xml, and:
<atom:link> elementThis file defines the RSS feed used by the FHIR registry to find the packages for the implementation guides published on your site.
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
From the publication directory, generate webroot/package-registry.json:
$ cd ~/src/publisher
$ java -jar ../publisher.jar -generate-package-registry webroot
In the ig-registry repo, create a branch for your changes.
$ cd ~/src/ig-registry
$ git checkout -b example-org-igs
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.