FHIR Chat · TOC Levels too restrictive · IG creation

Stream: IG creation

Topic: TOC Levels too restrictive

Eric Haas (Jul 10 2020 at 17:02):

@Lloyd McKenzie your decision to throttle the page toc levels to 1..3 is causing me headaches.

Since every markdown page header can only start with h3 level or the section numbering repeat the page title. That only give a single level page TOC which is too inflexible IMO.

For example this page: http://build.fhir.org/ig/HL7/davinci-deqm/branches/master/datax.html (building as I write this)
I need the h4 levels displayed in the toc header as these are key sections.

I propose we follow the Kramdown guidance here and make page toc levels to 1..4 and if you want to hide a header use the .no_toc class

e.g.

#### FOO
{:.no_toc}

Eric Haas (Jul 10 2020 at 17:06):

P.S. There is no way in Jekyll to override this default as far as I can find.

Lloyd McKenzie (Jul 10 2020 at 17:11):

I don't want authors to have to do anything to influence the TOC - if it's going to be variable, it should be determined by a script, not by the author. Author control adds to complexity and makes it too easy to get it wrong.

Eric Haas (Jul 10 2020 at 17:21):

I will continue to disagree ...but anyway... in addition, those annoying empty TOC boxes still persist. We could get rid of them with page level controls by adding more elements the to IG resources and defining them there ( but I question if this is easier)

...
page:
  - generation: markdown
    nameUrl: index.html
    extension:
      - url: 'http://hl7.org/fhir/us/davinci-deqm/StructureDefinition/extension-show_toc'
        valueBoolean: False #default = True
....

Eric Haas (Jul 10 2020 at 17:26):

and a site parameter...

...
  parameter:
    - code: max-toc-level
      value: "4" #default = 3
...

Jose Costa Teixeira (Jul 10 2020 at 17:31):

My take on this: Give Vanilla to everyone - no user should need to change the ToC from the defaults. If some institution wants to change the levels, they can mess with the template, enjoy the risks and handle the benefits.
But also allow some gourmet users to make advanced flavour - those users should be able to override sections of the ToC - to the extent that the template allows - institutions (e.g. IHE) may want to lock down the depth of their IGs.

Jose Costa Teixeira (Jul 10 2020 at 17:33):

I think the extension is heavy, but TBH it's because it is an extension. I had a similar / crazier idea, which would require changes to the ImplementationGuide resource.

Eric Haas (Jul 10 2020 at 17:33):

I question the original decision on the default since it only allow a single level.

Jose Costa Teixeira (Jul 10 2020 at 17:35):

@Eric Haas I think you missed 2 spaces before the word extension in your yaml..?

Jose Costa Teixeira (Jul 10 2020 at 17:40):

Changing this XML will not be a simple fix and will have impact on other parts.
I feel the pain though - not sure an extension will avoid further pain.

Eric Haas (Jul 10 2020 at 17:42):

Yes that is copy and paste error fixed....

Eric Haas (Jul 10 2020 at 17:44):

Well existing guides feel the pain having to reformat to conform.. Authors are not off the hook in either case.

Lloyd McKenzie (Jul 10 2020 at 17:59):

I'm not a fan of users in HL7 IGs doing any overriding. I would like to keep the learning curve the same for all IGs and behavior consistent regardless of who the author happened to be. I don't think we can technically prohibit overriding in most cases, but we should strongly discourage it. I'm perfectly happy with us to tune the appearance of the ToC - removing empty ToCs on those pages that legitimately are so short they don't need sub-sections (though those should be pretty rare). I'm also ok with making the generation of the ToC 'smarter' such that if going deeper will make a more useful ToC in certain cases, then we make it go deeper. I just don't want that to be an author-governed behavior. I already suppress ToC on HTML-authored pages when it's empty - because I can easily parse the HTML. I wasn't super clear on how to write Javascript to parse the markdown to accomplish the same think for markdown authored pages, so I didn't. But in principle, that could be done. And if we can come up with a set of criteria that would allow us to decide on when it's appropriate/reasonable to have a deeper ToC, we can certainly plug that logic into the generation process too.

Eric Haas (Jul 10 2020 at 18:02):

I already suppress ToC on HTML-authored pages when it's empty - because I can easily parse the HTML.

Eric Haas (Jul 10 2020 at 18:06):

OK I'll make a PR...

Eric Haas (Jul 10 2020 at 21:38):

I have liquid solution

Last updated: Apr 12 2022 at 19:14 UTC