provided html partials do not default behavior

[cboettig]

Bug description

The support for HTML partials is really nice and quite powerful. However, contrary to the documentation, quarto html template does not by default seem to be using it's own partials. i.e. , if we copy in the original title-block.html partial completely unmodified, this immediately breaks some quarto behavior, such as setting title-block-banner (https://quarto.org/docs/authoring/title-blocks.html#custom-backgrounds), which then has no effect.

Steps to reproduce

Follow the documented instructions on https://quarto.org/docs/journals/templates.html#template-partials to use the title-block template, providing the original title-block.html.

Now observe that setting title-block-banner (https://quarto.org/docs/authoring/title-blocks.html#custom-backgrounds), doesn't work any more.

Expected behavior

using the original template in unmodified form should be identical to not specifying a template, and thus should not break the behavior of other quarto elements.

Actual behavior

using the original template partial breaks title-block-banner (https://quarto.org/docs/authoring/title-blocks.html#custom-backgrounds).

Your environment

Linux (Ubuntu 22.04)

Quarto check output

cboettig@566ca0132982:~/cboettig/quarto-material$ quarto check

[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.1: OK
      Dart Sass version 1.55.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.3.450
      Path: /opt/quarto/bin

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.10.6
      Path: /usr/bin/python3
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with python3 -m pip install jupyter

[✓] Checking R installation...........OK
      Version: 4.3.1
      Path: /usr/local/lib/R
      LibPaths:
        - /home/cboettig/cboettig/quarto-material/renv/library/R-4.3/x86_64-pc-linux-gnu
        - /home/cboettig/.cache/R/renv/sandbox/R-4.3/x86_64-pc-linux-gnu/25ebdc09
      knitr: 1.43
      rmarkdown: 2.23

[✓] Checking Knitr engine render......OK

[cboettig]

reproducibility note: this occurs in website mode, which appears to customize layout elements in a way that extends but modifies the way the html template works? I think I generally understand the workflow of the process of knitr -> markdown -> pandoc + lua filters -> html, but I'm pretty fuzzy on what happens when I invoke the 'website' type and try adding navigation...

[dragonstyle]

Title block banner is actually implemented using partials (it provides an alternative title template), so it is incompatible with user templates.

This is currently by design and something that I think we could continue with (we introduce a new manuscript style title block in Quarto 1.4 that also uses an alternative template) unless you have a good case for why we should try to cram all the customization into a single template...

The banner style title block is here, in case you'd like to use that as a baseline implementation: https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/formats/html/templates/banner/title-block.html

[cboettig]

@dragonstyle Thanks for your help and my apologies for not filing a clear issue, I am still figuring out how quarto renders.

I had the wrong assumption that quarto used only pandoc templating for html templating; I realize now that quarto websites, while still inheriting from "format: html" behavior, actually accomplish most of their templating outside of pandoc using your Embedded Javascript Templates (these templates: https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/projects/website/templates).

This makes total sense to me -- EJS looks like a much richer templating system than pandoc's. Unfortunately, there is no support that I can see for using partials or other mechanisms for the user to modify or extend the EJS templates, other than a passing mention in the use of listings.

Specifically, I am seeking to modify the "nav" templates -- as I discussed with @cscheid after his presentation the other day, I am looking to adapt the look and feel of quarto a little more, much like one could already do using other static site generators like jekyll or hugo that have been popular in our #rstats community for some time. (yes, I know quarto has hugo markdown format, but I'm looking to extend the very nice quarto website format, not throw that all out and go back to hugo). For instance, I'd like to add support for the "transparent" and "blur" navbars in this bootstrap-5 based theme (https://demos.creative-tim.com/material-kit/) to my quarto-based websites.

If I understand correctly, this isn't currently in scope? Do you see this as something that quarto could do in future? I think it would be sufficient if users could just supply custom EJS templates, based off of the existing ones -- I'm not much of a CSS expert but it looks like we could get quite far if we could only just add an additional class or two onto the nav items in those EJS templates, but I just can't see how to do that.

[dragonstyle]

Ahhh, I see.

You are correct, right now the templates that drive the website 'envelope' are not really accessible externally (there isn't an ability to provide a custom version nor really to reach in directly and customize them very directly.

I could certainly see eventually allowing custom templates, though we have some real work to do to make the behavior a little more well specified so developers of custom templates have an API of sorts to work against. I think the other question would be whether there are modifications that we could support in the short term to give you more hooks to work with (e.g. as you noted, forwarding custom classes, etc...). That would definitely be a smaller lift if there are things you'd like to see.

[cboettig]

Thanks, lovely!

Yes, long term at least I'd love to see some kind of developer API to extend the EJS templates. I've never learned javascript but EJS looks really quite nice, and somewhat familiar for those of us who struggled our way through hugo (or before that, jekyll) without knowing go or ruby either...) A nice developer API for this is probably a big lift.

I'd be keen to try a simpler work-around though. Would it be possible to just expose a mechanism to drop-in a customized ejs file that would override the default, e.g. nav-before-body.ejs ? This would be crude of course since the user would be responsible for grabbing a copy of the original template and making only non-breaking modifications to it, and would restrict the user to the current set of .ejs template files (or maybe just a subset thereof). But it would at least provide an 'escape hatch' into customizing these templates without much additional machinery?

[cboettig]

Closing this since this isn't a bug in html partials. thanks for the help. I've opened a discussion thread for a feature request on possible small changes that might give users ability to modify EJS templates. https://github.com/quarto-dev/quarto-cli/discussions/6552