Skip to content

Keep the Jekyll variable in the downloads page out of the preprocessing - #19

Merged
patrick-werner merged 2 commits into
masterfrom
fix-validation-link
Aug 31, 2026
Merged

Keep the Jekyll variable in the downloads page out of the preprocessing#19
patrick-werner merged 2 commits into
masterfrom
fix-validation-link

Conversation

@patrick-werner

Copy link
Copy Markdown
Collaborator

Fixes the broken link reported by QA, e.g. on
the xtehr-1.0 preview:

ERROR: downloads.html#/html/body/div/div/div/div/div/p/a at Line 256, column 337:
The link 'validation.html' for "validating FHIR profiles and resources" cannot be resolved

Not specific to that branch — a build of master reproduces it.

Cause

Two Liquid engines run over the same file. downloads.liquid.md is a template, so the
preprocessing renders it before Jekyll ever sees it, and both use {{ }}. liquidjs
resolves site.data.fhir.path against context-<Rx>.json, which has no site variable,
so it becomes the empty string:

ig-src                  ({{ site.data.fhir.path }}validation.html)
after preprocessing     (validation.html)
rendered HTML           href="validation.html"

What should have been http://hl7.org/fhir/R4/validation.html turned into a relative link
to a page the guide does not have. site.data.fhir.path comes from temp/pages/_data/fhir.json,
which the publisher writes before running Jekyll — it holds http://hl7.org/fhir/R4/ in the
R4 build and the R5 URL in the R5 build, which is precisely why it should not be replaced
by a hardcoded URL.

Change

{% raw %} hands the expression through the first pass. liquidjs consumes the tag and
emits its content verbatim, so Jekyll receives a plain expression and resolves it as usual.

Renaming the file to downloads.md would also work, but it needs Liquid for its
{% if isR4 %} / {% if isR5 %} blocks.

The README gains a short subsection on the collision. This was the only Jekyll
expression in a template — I checked every .liquid. file for site., page., include.
and {% include %} — but the publisher offers a dozen data files behind site.data.*, and
nothing reports the mistake: the page still renders, the link is just wrong.

Verification

Full R4 publisher build, before and after:

before after
Broken Links 1 0
href in downloads.html validation.html http://hl7.org/fhir/R4/validation.html

validation.html no longer appears in qa.txt. Both targets exist (http://hl7.org/fhir/R4/validation.html
and the R5 one return 200), and the expression is preserved in the generated downloads.md
of both FHIR versions.

The remaining Errors: 1 is a separate, pre-existing content finding and is untouched here.

The link to the validation overview on the downloads page was built from
site.data.fhir.path, which the IG publisher fills in with the base URL of the
FHIR release. downloads.liquid.md is a template, though, so the preprocessing
renders it before Jekyll ever sees it, and liquidjs resolves the expression
against context-<Rx>.json. There is no site variable there, so it became the
empty string and the link pointed at validation.html inside the guide, which
does not exist:

  ERROR: downloads.html ... The link 'validation.html' for "validating FHIR
  profiles and resources" cannot be resolved

Wrapping the expression in {% raw %} hands it through the first pass. The tag
is consumed there, so Jekyll receives a plain expression and resolves it to
http://hl7.org/fhir/R4/validation.html, and to the R5 page in the R5 guide.

Document the collision in the README as well. This was the only Jekyll
expression in a template, but the publisher offers a dozen data files behind
site.data, and nothing reports the mistake: the page renders, the link is
just wrong.
The variable table listed five of the entries in context-R4.json and
context-R5.json and left out eu-core-r-code, the -yaml markers and the one
whose key ends in a space. The last two are the ones that need explaining:
{{R }} renders as nothing and holds the marker column for lines that belong
to both versions, and {{R4-yaml}} / {{R5-yaml}} are the comment markers for
files in which // does not start a comment.
@patrick-werner
patrick-werner merged commit 992bd68 into master Aug 31, 2026
3 checks passed
@patrick-werner
patrick-werner deleted the fix-validation-link branch August 31, 2026 13:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant