Setting up to publish Implementation Guides

From Health Level 7 Belgium Wiki

Check Java

  • Make sure you have a java VM in your computer. A JRE will do. OpenJDK works.
    • in a command line, run
java -version

you should have a result like

java version "1.8.0_60"
Java(TM) SE Runtime Environment (build 1.8.0_60-b27)
Java HotSpot(TM) 64-Bit Server VM (build 25.60-b23, mixed mode)


Install Jekyll


Install Node / NPM and sushi

  • see if node is installed : run this on a command line window:
 npm -v

you will either get an error or a version number. If you get a version number, you're good.

  • once it is installed, install sushi and shorthand by running these two command lines:
 npm install -g sushi
 npm install -g fsh-sushi
  • after the install, check that sushi is correctly installed. Run the command
 sushi -v

you should receive a response like this

SUSHI v1.1.0 (implements FHIR Shorthand specification v1.1.0)

if not, retry to install sushi using the commands above


Setup your computer folders

  • Create a folder in your computer for work on this and other implementationguides. For example inside your Windows "Documents" folder:
c:\users\<user>\Documents\ImplementationGuides
  • Create a folder for your first implementation guide:
c:\users\<user>\Documents\ImplementationGuides\my-first-ig


Get an empty IG to start

 c:\users\<user>\Documents\ImplementationGuides\my-first-ig\_genonce.bat
  • you should NOT have a folder and then the files - this is unwanted:
c:\users\<user>\Documents\ImplementationGuides\empty-ig-master\my-first-ig\_genonce.bat
    • You can later add more implementation guides to the same folder. For example when you have 3 implementation guides, `hl7-be`, `my-first-ig`, `ehealth-ig`, you can have a folder structure like
 c:\users\<user>\Documents\ImplementationGuides
      \hl7-be
      \my-first-ig
      \ehealth-ig


Download the publisher and update the scripts

  • Run (by double-clicking or executing in a command line) the file
 _updatePublisher.bat
  • Answer Y to the questions

This will download the publisher to your computer (in this case, to the input-cache folder).

  • Confirm that there is a file called publisher.jar in the input-cache folder, for example
c:\users\<user>\Documents\ImplementationGuides\my-first-ig\input-cache


Publish the ImplementationGuide

  • Run (by double-clicking or executing in a command line) the file

_genOnce.bat

You will see a lot of progress indicators. This should take 1 to 5 minutes, depending on your machine. If you have an error, reach out, we'll figure it out.


Check the result

  • After an implementation guide build runs locally, the output is in the folder .\output. Open (in a browser) the file
output\index.html


Optional: copy the publisher jar to the parent folder

Every time you get an Implementation Guide, you need to run the _updatePublisher. If you do this, you will get the same publisher jar (100 mb) in every one of your Implementation Guides' input-cache folder If you run or maintain several Implementation Guides, you may want to use only one Publisher Jar, instead of many. To do this, you only have to copy the file

 publisher.jar

to the parent folder above your implementation guide. In our example, copy the publisher.jar from the input-cache folder to the folder

c:\users\<user>\Documents\ImplementationGuides

If you do this, you will no longer need to run the _updatePublisher every time you download an implementation guide