Stream: IG creation
Topic: pagecontent ordering in TOC
Joe Paquette (Jan 28 2021 at 15:48):
I'm working on a simple IG based on the fhir.base.template. I wamt to add several markdown files for adding specific pages accessible in the IG TOC. I understand the rendering uses the file name for the TOC and page title. How does the IG publisher determine the ordering of these pages?
I thought I read somewhere to prefix the file name with a number to define the order, but haven't been able to find that reference. I tried prefixes such as "1-MyPage.md", "2-AnotherPage.md" and "1.MyPage.md", "2.AnotherPage.md", but the leading number was treated as text in the page title in both examples. What is the "secret sauce" to specifying the page order? I'd rather not have to use pages: in sushi-config.yaml because I rather let the publisher render the content for me.
David Pyke (Jan 28 2021 at 16:07):
Sushi uses 1_pagename.md to set the order
David Pyke (Jan 28 2021 at 16:07):
index.md is the home page
Joe Paquette (Jan 28 2021 at 16:58):
The underscore is the "secret sauce" and it worked as expected. Many thanks!
Chris Moesel (Jan 28 2021 at 18:13):
Joe Paquette said:
I'd rather not have to use
pages:in sushi-config.yaml because I rather let the publisher render the content for me.
To be clear, the IG publisher doesn't render the pages differently in either case; it's just whether or not SUSHI builds up the page hierarchy for you or if you control it yourself. The downside of using pages: is that you have to manually list your pages (and remember to add them as you create new pages), but the upside is better control of the page structure (nested pages!), better control of titles (divorced from filename), and cleaner URLs (since you don't need to put numbers in the filenames).
Obviously we offer the page number prefix scheme because we know some people will prefer it, but I just wanted to be sure that the tradeoffs are clear!
Eric Haas (Jan 28 2021 at 18:29):
Sushi uses 1_pagename.md to set the order
Can you point me to doco on this? I was under the impression that the order was based on the order in the file tree ( alpha based and driven by GitHub) when letting sushi assemble the IG resource? ( which I Love BTW - so much better than my version)
Chris Moesel (Jan 28 2021 at 18:33):
@Eric Haas, it is documented here:
N_pagename.xml|md: If present, these files will be generated as individual pages in the IG. The leading integer (N) determines the order of the pages in the table of contents. Adding a leading integer is optional, and in the absence of a leading integer, SUSHI will sort the pages alphabetically. The order of the pages can also be explitly specified with the
pagesproperty in sushi-config.yaml.
Chris Moesel (Jan 28 2021 at 18:35):
Special treatment (vs just alphabetic) is important so that 10 comes after 9 and not before 2.
Joe Paquette (Jan 28 2021 at 20:10):
Thanks @Chris Moesel! That is really helpful information. I didn't fully understand how that worked, so now I can make a more informed decision as to if/when to use pages: in our project. I'm still learning the details of Sushi/IG Publisher. Thanks again for the clarifications.
Chris Moesel (Jan 28 2021 at 20:34):
You're very welcome!
Last updated: Apr 12 2022 at 19:14 UTC
