FHIR Chat · Linking md pages as table of contents

Stream: IG creation

Topic: Linking md pages as table of contents

Brian Reinhold (Sep 22 2018 at 10:28):

In Simplifier I had created a number of markdown pages. They were linked in a tree structure. In the publisher, I have xhtml files which make up the 'home', 'overview', profiles, etc. links across the top of rendered page. When I click on the 'profiles' page, I display the table of structure definitions. What I would like to have after that is a table of links (like a table of contents) which when clicked on brings one to one of my many markdown pages describing how each of these profiles and how they are mapped from 20601. How would I do this? I know how to link markdown pages but I am not sure how I should place them in folders etc. Don't know if that would work anyways in the context of the publisher..

I tried the following:
I put in the header of a markdown file this:

## Phd Base Observation Profile <a name="PhdBase"></a>

and in a markdown page 'included' by using the ugly

<div>
                <p>
                {% capture p1 %}{% include profiles.md %}{% endcapture %}
                {{ p1 | markdownify }}
                </p>
</div>

I put the following link:

# Table of Contents
[Phd Base Observation Profile](#PhdBase)

Upon rendering it generated a nice looking link that was clickable but went nowhere. I placed both markdown pages in the '_includes' directory. That's probably the problem. I do not know where to place this linked page or tell the IG publisher where to find it.

tried this as well in the included markdown page

{% link _include _includes/BaseObservationProfile.md %}  or {% link _includes/BaseObservationProfile.md %}

In the first case IG Pub gave error
ke sure the document exists and the path is correct.
_includes/BaseObservationProfile.md' in tag 'link'.
(which is correct)

In the second case IG pub gave error
ke sure the document exists and the path is correct.
s/BaseObservationProfile.md' in tag 'link'.

Lloyd McKenzie (Sep 22 2018 at 14:32):

You really should use one of the existing frameworks. They handle this sort of stuff for you. Have you looked at the SDC IG and DaVinci IG? The former is simpler. The latter shows how you can use markdown

Eric Haas (Sep 22 2018 at 16:37):

Assuming you have a layout page called default:

you have a profile page profiles.md in the pages directory:

___
layout: default
title: foo
etc...
___

<!-- list o profile-->
 ### List o Profiles

{%   include list-simple-profiles.xhtml %}  <!-- already created by the build-->

<!-- my table of profiles in markdown -->
### Table o Profiles

|Row|Profile Name|Link to Profile|
|---|---|---|
|1|Foo|[Foo]|
|2|Bar|[Bar]|

[Foo]: (StructureDefinition-foo.html)  <!-- SD file also generated by the build -->
[Bar]: (StructureDefinition-foo.html)

Eric Haas (Sep 22 2018 at 16:39):

you can include the markdown files directly in most places:

{% include my_file.md %} should work .... only in a select few case do you need to use markdownify for example in the template files.

Eric Haas (Sep 22 2018 at 16:40):

Also Lloyd is right should use the existing framework like in SDC or DEQM

Brian Reinhold (Sep 22 2018 at 19:54):

Also Lloyd is right should use the existing framework like in SDC or DEQM

@Eric Haas @Lloyd McKenzie
I have no problem including markdown pages, what I can't do is make links to them.

I am also following some framework; whatever the PoCD guide is doing (not that I understand how it all works). The PoCD guide has a set of xhtml files in its pages directory, each of which uses the FHIR HL7 headers, navigation bar, and footers. The files correspond to the home, profiles, etc. 'links' posted in the nav bar. I can use an ugly command in these xhtml files to include a markdown file by putting the file in the pages/_includes directory.

But once in the page, the only way I can make links to my other pages is to use the markdown [ link name ] (link) and include that page in the current page. If I have 12 such pages, it makes the rendered page QUITE big.

What I want to do is have links that open up a new page instead of just hopping down to the correct location in the same page.

Lloyd McKenzie (Sep 22 2018 at 20:00):

If you make the link to pagename.html, the link should allow you to easily navigate to other pages. There's a whole lot of that in the Davinci CRD IG

Brian Reinhold (Sep 22 2018 at 20:06):

If you make the link to pagename.html, the link should allow you to easily navigate to other pages. There's a whole lot of that in the Davinci CRD IG

@Lloyd McKenzie The only missing link (no pun intended) for me is how do I tell the IG Publisher to generate an html file out of my markdown file? I think I actually was able to open the markdown page as a link in a separate page, but I got the RAW markdown file ... totally useless.

I figured this out so far: Put the md file in pages directory and add this at the start of the md file

---
title: Phd Base Observation Profile
layout: default
active: BaseObservationProfile
---

I had NO idea. At least this gives me an html version of the markdown file. But now I need a layout file. When I try and reference the html in my document with this

[Base Observation Profile]({{site.data.fhir.igName}}BaseObservationProfile.html)

I get the warning that the layout file does not exist and clicking on the reference (once rendered) gives me a file not found error though it DOES exist in the output directory and I can click on it in the output directory and it is rendered (not in the format of the rest of the pages though).

If you are not a web programmer (know nothing about html, js, css) writing all these raw files is a daunting task. Further I don't know what the IG Publisher does of this web work and what I have to do.

Brian Reinhold (Sep 23 2018 at 21:00):

Well, I found a layout file from another project with the HL7 headers and navbars and borrowed that. Then I stumbled on a great StackOverflow which explaned how to do a lot of undocumented Jekyll stuff and finally I was able to make a link to my md (converted to html) files.
Only took three days to do it!

Oliver Egger (Sep 24 2018 at 06:14):

@Brian Reinhold would it be possible to share the stackoverflow/jekyll post?

Brian Reinhold (Sep 24 2018 at 08:50):