FHIR Chat · IG Publisher - index.md · implementers

Stream: implementers

Topic: IG Publisher - index.md

Dan Gottlieb (Dec 21 2020 at 21:59):

I'm trying to rebuild v1.5 of the bulk data IG on top of the base provided by the sample-ig repo. However, when I change the index.html file in pagecontent directory to an index.md file, I get the following build error:

java.lang.Exception: Template based HTML file index.html is missing source file index.xml
    at org.hl7.fhir.igtools.publisher.Publisher.applyPageTemplate(Publisher.java:5991)
    at org.hl7.fhir.igtools.publisher.Publisher.applyPageTemplate(Publisher.java:6005)
    at org.hl7.fhir.igtools.publisher.Publisher.generateSummaryOutputs(Publisher.java:5850)
    at org.hl7.fhir.igtools.publisher.Publisher.generate(Publisher.java:4910)
    at org.hl7.fhir.igtools.publisher.Publisher.createIg(Publisher.java:888)
    at org.hl7.fhir.igtools.publisher.Publisher.execute(Publisher.java:732)
    at org.hl7.fhir.igtools.publisher.Publisher.main(Publisher.java:8414)

I thought the index page could be markdown - is there a setting somewhere I need to change? Thanks!

Lloyd McKenzie (Dec 21 2020 at 22:04):

Is it referenced in your IG as a page?

Eric Haas (Dec 21 2020 at 22:05):

yes the index page can be markdown.

verify the information is correct in the IG resource:

here is an example:

...
    -   system: url
        value: https://confluence.hl7.org/display/AP/Argonaut+Project+Home
definition:
    page:
        generation: html
        nameUrl: toc.html
        page:
        -   generation: markdown  # <<<<<< indicate is markdown here
            nameUrl: index.html
            title: Home
        title: Table of Contents
    parameter:
    -   code: copyrightyear
....

Dan Gottlieb (Dec 21 2020 at 22:08):

Ah, the generation param is the input format - I had assumed it was the output format. Thanks Eric!

Dan Gottlieb (Dec 21 2020 at 22:09):

Btw, do you know if these items are documented somewhere?

Dan Gottlieb (Dec 21 2020 at 22:26):

Specifically, I'm trying to figure out how to replicate the following features with the current version of the IG Publisher:

1. Build page paths in subdirectories like /export/index.html to avoid breaking people's links (I tried using the path as the nameUrl and nesting page elements, neither of which seemed to work, and all the IGs I looked at just use a flat structure in the pagecontent directory)
2. Include files in these subdirectories that get deployed with the IG like https://hl7.org/fhir/uv/bulkdata/authorization/sample-jwks/RS384.public (the publisher seems to object to these since they're not md or xml)
3. Add the SMART logo to the header (I tried updating /template/includes/fragment-header.html, but it gets overridden by the template value in ig.ini of hl7.fhir.template)
4. Add Boston Children's joint copyright to footer (I tried updating /template/includes/pageend.html, but it gets overridden by the template value in ig.ini of hl7.fhir.template as well)

Jose Costa Teixeira (Dec 22 2020 at 00:03):

1. Why do you want that structure not to be flat? I don't think it is possible but I may be wrong

Jose Costa Teixeira (Dec 22 2020 at 00:03):

3 and 4 require a template customization.

Jose Costa Teixeira (Dec 22 2020 at 00:06):

Not sure this helps: http://build.fhir.org/ig/FHIR/ig-guidance/template.html

Lloyd McKenzie (Dec 22 2020 at 04:01):

1. The publisher does not allow sub-folders for generated content. It was just too messy to get cross-links to work properly. All links need to presume all generated pages are in the same (root) folder.
2. The only way to get files put anywhere other than the root is if they're defined in the template
3. Take a look at how to create your own override template here: https://github.com/HL7/fhir-cdisc-mapping
4. Seeing how the header gets overridden in #3 should give you an idea of how to override the footer too. You might actually want to define a 'standard' template for Boston Children's that could be used by multiple IGs - check out the Da Vinci template here: https://github.com/HL7/ig-template-davinci

Eric Haas (Dec 22 2020 at 04:20):

actually I think for

2) put the sample jwks them in the images folder and can reference them and include them directly from the output directory, for example... https://argonautproject.github.io/patient-lists/cat.jpg

image.png

Eric Haas (Dec 22 2020 at 04:25):

sadly for 3) and 4) the the current templates don't allow for a secondary sponsoring org link besides HL7. I think its a lot to ask for folks to create new templates to add a cosponsor to an HL7 guide. maybe we can add a parameter for a cosponsorship and tweak the standard templates?

Eric Haas (Dec 22 2020 at 04:29):

for 1) I see how it makes sense from a web publishing perspective and allows the file structure to follow the web page structure. IN practice, I found that devilishly tricky in Jekyll even before the templates when publishing the SMART launch guide probably due to the ig-publisher trying to flatten everything out in the temp file. :-(

Lloyd McKenzie (Dec 22 2020 at 06:40):

Ah, I missed that this was for an HL7 IG. The copyright can be overridden by an IG-specific template folder declared within the IG - as CDISC did.

Dan Gottlieb (Dec 22 2020 at 16:42):

Thanks @Jose Costa Teixeira , @Lloyd McKenzie and @Eric Haas ! To summarize my understanding (please correct me if I'm wrong):

1. Sub-folders are no longer supported in the IG builder - I'll move the IG to a flat structure. I was hoping to keep the hierarchical structure from the STU1 publication to maintain people's inbound links, but perhaps some redirect magic can be done on the HL7 server config to facilitate this when we deploy the new version post-ballot?
2. Putting these artifacts in the images folder works! Same issue as #1 with external inbound links breaking though.
3. (and 4) I've added an IG template folder (per the super helpful CDISC example) and down the road we can look at extracting that into an external SMART template (per DaVinci) if there are other use cases.

Lloyd McKenzie (Dec 22 2020 at 19:54):

1. I don't think they ever were supported?

Dan Gottlieb (Dec 22 2020 at 20:51):

I'm not sure if they are officially supported :), but they're being used in
https://github.com/HL7/bulk-data/tree/master/spec and seem to build ok at http://build.fhir.org/ig/HL7/bulk-data/

Eric Haas (Dec 23 2020 at 04:32):

use in SMART launch as well.

Grahame Grieve (Dec 23 2020 at 05:20):

Sub-folders are no longer supported in the IG builder

This has got nothing to do with the IG publisher - it's up to the template.

Lloyd McKenzie (Dec 23 2020 at 14:49):

How does the template influence anything? Is the issue that all sub-folders need to be specifically identified by parameter in the IG?

Eric Haas (Dec 23 2020 at 16:29):

here is a typical template ('_layout' in Jekyll speak) in the life of a pre template ig using nested page directories....

<!-- this liquidi is  to get the internal relative references to work -->
{% assign base = '' %}
{% assign depth = page.url | split: '/' | size  %}
{% if depth == 2 %}{% assign base = '../' %}
{% elsif depth == 3 %}{% assign base = '../../' %}
{% elsif depth == 4 %}{% assign base = '../../../' %}
{% endif %}

{% if page.template %}
{% assign base = '' %}
{% endif %}

<!DOCTYPE html>
<!-- saved from url=(0043)http://hl7.org/fhir/2016May/FHIRPath.html -->
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>


  <title>{{page.title}}</title>

  <meta content="width=device-width, initial-scale=1.0" name="viewport"/>
  <meta content="http://hl7.org/fhir" name="author"/>

  <link rel="stylesheet" href="{{base}}dist/fhir.css"/>  <!-- THEN use  {{base}} in here everwhere to keep all the nesting straight-->
  <link rel="Prev" href="{{base}}history/index.md"/>

    <!-- Bootstrap core CSS -->
    <link rel="stylesheet" href="{{base}}dist/bootstrap.css"/>
    <link rel="stylesheet" href="{{base}}dist/bootstrap-fhir.css"/>
    <link rel="stylesheet" href="{{base}}dist/bootstrap-glyphicons.css"/>

    <!-- Project extras -->
    <link rel="stylesheet" href="{{base}}dist/project.css"/>
    <link rel="stylesheet" href="{{base}}dist/pygments-manni.css"/>
    <link rel="stylesheet" href="{{base}}dist/jquery-ui.css"/>

....

Eric Haas (Dec 23 2020 at 16:33):

Like I said above, I had struggled with this and found it a pain to get the relative reference and includes that were in another directory to work, so I personally prefer flat directories since the temp flattens everything anyway. ( I don't believe that is how Jekyll out of the box works)

Grahame Grieve (Dec 23 2020 at 18:25):

right. sub-folders are painful. but it's the template that decides how the files are laid out (in the config). the IG publisher just does what the template says

Lloyd McKenzie (Dec 23 2020 at 18:33):

I'm still not really understanding. The template points to the folder that holds 'pages'. What does the template need to do to have the IGPublisher process sub-folders within that folder/those folders?

Grahame Grieve (Dec 23 2020 at 18:44):

the template decides how the resources are generated

Lloyd McKenzie (Dec 23 2020 at 20:33):

I don't think this is about generating resources, it's about retaining hierarchy of pages?

Frank Oemig (Dec 24 2020 at 08:35):

Flat structures are easier to maintain - definitely. However, I changed my v2 html rendering to directory structures, because many thousand files are hardly maintained in a single directory...

Last updated: Apr 12 2022 at 19:14 UTC