Stream: IG creation
Topic: markdown page title
Jose Costa Teixeira (Mar 23 2022 at 21:13):
For discussion: Would we consider adding markdown page titles (and possibly another property) as frontmatter?
Jose Costa Teixeira (Mar 23 2022 at 21:14):
this could be useful for sushi authoring (and possibly picked up by the templates if it is interesting and feasible) :
Jose Costa Teixeira (Mar 23 2022 at 21:15):
Normally, sushi takes the page title from the file name, or from the sushi-config.yaml, if one is provided.
If we want to have a human-friendly page title, we need to add it to sushi-config.yaml which disables the automatic building of the ToC.
Jose Costa Teixeira (Mar 23 2022 at 21:27):
I would like to have frontmatter as a way to indicate the page title. Like this:
https://raw.githubusercontent.com/costateixeira/ddcc/main/input/pagecontent/functionalrequirements.md
Chris Moesel (Mar 23 2022 at 21:32):
@Jose Costa Teixeira -- you call out SUSHI, but the same limitation exists for workflows using IG Publisher directly (without SUSHI), right?
Lloyd McKenzie (Mar 23 2022 at 21:36):
I would definitely like it if SUSHI authors could easily control their HTML page names such that they aren't long and ugly or driven by ToC hierarchy. Page names matter...
Jose Costa Teixeira (Mar 23 2022 at 21:48):
@Chris Moesel I did mention sushi and the templates (IIRC the templates is where the toc magic happens)
Jose Costa Teixeira (Mar 23 2022 at 21:50):
But yes, ig templates and publisher don't really process frontmatter.
Jose Costa Teixeira (Mar 23 2022 at 21:51):
I have to investigate how we could use that frontmatter for non-sushi-driven pages. @Chris Moesel are you suggesting that if we fix that, then sushi would just rely on it?
Chris Moesel (Mar 23 2022 at 21:55):
I just wanted to be sure it's not a deficiency in SUSHI itself. @Lloyd McKenzie -- Don't you mean all IG authors (not just SUSHI authors)? Wouldn't a non-SUSHI author have to fully specify pages in the ImplementationGuide JSON in order to control page names? Actually, don't they have to do that anyway? I guess my point is, I don't think that SUSHI makes it harder to control page names; it just provides a meaningful default if you don't provide them.
Chris Moesel (Mar 23 2022 at 21:57):
And @Jose Costa Teixeira -- Yes, I think SUSHI could look into front-matter to grab a page title if the IG Publisher / Template system were to start supporting front-matter. My understanding is that right now, IGP chokes on front-matter.
Jose Costa Teixeira (Mar 23 2022 at 21:58):
@Chris Moesel sushi has no deficiency, it's just a possible enhancement. I was working with sushi and I thought of this idea.
Jose Costa Teixeira (Mar 23 2022 at 22:00):
@Lloyd McKenzie When does the template use processPages to create the toc? I presume it's well before jekyll runs?
Jose Costa Teixeira (Mar 23 2022 at 22:01):
(if it were after, we could get jekyll to pick that frontmatter for us, jekyll knows how to)
Chris Moesel (Mar 23 2022 at 22:02):
Ah. So this is a little different from the bring back front matter discussion then, right? Related, but slightly different?
Jose Costa Teixeira (Mar 23 2022 at 22:08):
actually it is the same, but simpler: I was looking for 2 features:
- adding the title (it's really common, and the alternative is cumbersome)
- excluding a page from being added to the IG at all, if a given tag is there (e.g. "exclude: true" or something)
Jose Costa Teixeira (Mar 23 2022 at 22:09):
so, for each page, I'd define those 1 or 2 variables, and tell IG authors that they can use it, but they don't have to at all
Jose Costa Teixeira (Mar 23 2022 at 22:10):
(for feature 2 above, we can simply exclude the page if the file's text lenght is <4 characters, for example - but I don't know how to do that for both XHTML and MD). So I'm really looking into 1 variable
Lloyd McKenzie (Mar 23 2022 at 22:11):
My experience has been that sushi IGs tend to end up with names that look like this: "specification__behaviors__requesting_additional_information_from_the_user.html" instead of "requesting-info.html" or something else that's more reasonable. I've presumed that's driven by how SUSHI manages the determination of page names.
Lloyd McKenzie (Mar 23 2022 at 22:11):
If you're not using sushi, then you're always naming your pages outright and page name and page title are completely independent.
Lloyd McKenzie (Mar 23 2022 at 22:11):
(as they should be)
Jose Costa Teixeira (Mar 23 2022 at 22:12):
right. Sushi has an optional page title parameter otherwise it assumes page title = filename (i guess?)
Jose Costa Teixeira (Mar 23 2022 at 22:13):
@Lloyd McKenzie for non-sushi, and for xhtml, is the the page title in the xhtml file?
Jose Costa Teixeira (Mar 23 2022 at 22:13):
Or does it have to be specified in the ig xml?
Lloyd McKenzie (Mar 23 2022 at 22:14):
Page names and titles are both specified in the ig.xml for ad-hoc pages. For resource pages, the page names are generated based on artifact ids. Titles come from the artifact or the ig.xml.
Jose Costa Teixeira (Mar 23 2022 at 22:17):
do we want the abiity to optionally define a page title inside the xhtml as well as markdown?
Lloyd McKenzie (Mar 23 2022 at 22:18):
Not really. I don't want titles defined in markdown either.
Jose Costa Teixeira (Mar 23 2022 at 22:19):
but that forces us to either do the whole page structure in the IG (for all pages) or just accept that pages will, at best, get their title from the filename (as sushi does)
Lloyd McKenzie (Mar 23 2022 at 22:21):
I don't understand why doing the page structure in the IG is problematic. You want to manage hierarchy and stuff there anyhow.
Jose Costa Teixeira (Mar 23 2022 at 22:23):
it's for default behaviour - when a user doesn't care and just trusts the tool defaults, sushi does that bit automatically (add the pages to the IG). but the moment that the user still trusts those tool defaults, and just wants to add a title to one single page, then they have to create the page content.
Elliot Silver (Mar 23 2022 at 22:32):
Are you suggesting a way to name pages independent of indicating the TOC? Would an IG parameter (or similar) that says "use this name for this page", which would be omitted for most pages most of the time, work?
Jose Costa Teixeira (Mar 23 2022 at 22:35):
Elliot Silver said:
Are you suggesting a way to name pages independent of indicating the TOC?
Yes
Would an IG parameter (or similar) that says "use this name for this page", which would be omitted for most pages most of the time, work?
not a parameter, i think. that is pretty much what sushi is doing.
Jose Costa Teixeira (Mar 23 2022 at 22:36):
So, if this doesn't move forward, @Chris Moesel there may be an alternative for sushi authors:
Elliot Silver (Mar 23 2022 at 22:37):
Jose Costa Teixeira said:
not a parameter, i think. that is pretty much what sushi is doing.
Going from memory, I thought sushi was using the TOC info to set the page names. I could very well be wrong on this.
Jose Costa Teixeira (Mar 23 2022 at 22:37):
could sushi have a parameter that, when pages are added, does not remove all the other pages?
i.e. if I add the title in one page only, all the others would stay there, but this one would have its title changed
Chris Moesel (Mar 24 2022 at 00:55):
@Jose Costa Teixeira -- I think we could come up w/ something like that -- but probably not exactly that because there are lots of existing IGs that depend on (or at least expect) the current behavior. But I understand the goal.
Chris Moesel (Mar 24 2022 at 00:59):
Eric Haas (Mar 24 2022 at 15:17):
Front matter matters! same discussion as before.
Last updated: Apr 12 2022 at 19:14 UTC
