Extensible / customizable quarto website templates (e.g. permit customize EJS templates)

[cboettig]

Description

Quarto's website type is obviously an immensely popular aspect of the platform, but unlike other elements of quarto or other static site generators where users can customize layout templates, Quarto's website features are mostly hardwired in Embedded Javascript Template (EJS) files.

It would be very nice if users could swap out some of these existing templates for comparable user-supplied alternatives. Quarto already allows users to swap out the pandoc html.template in this way, simply by providing a path in the _quarto.yml metadata:

format:
  html:
    template-partials:
      - assets/partials/title-block.html
      - assets/partials/toc.html

I wonder if it would be possible to simply provide a similar template-partials: field on the website block of the yaml that would behave similarly, allowing users to plug in, e.g. a custom nav-before-body.ejs in place of the one baked into the CLI? Maybe something like:

website:
  navbar:
    template-partials:
      - assets/partials/nav-before-body.ejs

While customizing the EJS templates would still be a somewhat advanced feature, (users would be responsible for understanding EJS, which after all seems to be a very nice and well documented templating system), I think this would at least open the door to customizing these design elements and maybe offering community-contributed extensions. At the moment, this whole aspect of quarto is a bit walled off from community extensions.

I realize the EJS template partials weren't initially introduced with the idea that users would customize them, and that there's an argument to be made for a more fully-flushed out user interface for web templating. That's obviously a heavy lift, but meanwhile I'm hoping that just changing the path of these templates from the hardwired location to a user-supplied path, matching the existing pandoc template customization method already available, is not impossible?

[jimjam-slam]

@cboettig I'm not well placed to speculate on how possible this is for other parts of the website, but it is already a thing for listings, so that's something! Being able to make your own listing templates really lets Quarto compete with other blogging engines IMO.

The website format is already pretty configurable outside that, between HTML include options, custom themes and other website and HTML options, as well as either just directly writing Markdown (or HTML, using a {=html} chunk) into a particular page's Quarto doc body or just replacing the HTML template wholesale, as you describe. I totally get wanting to have other options, though!

[cboettig]

@jimjam-slam yup, I'm aware of listings and the html options, though I don't believe the html options let you replace the website template whole-sale. It's not clear to me how it all works either, but I believe the EJS website templates are applied after the html pandoc templates are applied, and other than listings I don't think they can be customized.

For instance, I'm particularly interested in being able to customize the behavior of navigation menus. nav-related templating makes up a significant bit of those templates, and is unique to website format, unlike elements in the (generally single-page-oriented) html format. I love all the built-in support for quarto navigation menus -- top bar, side bar, footer, right-hand menu etc, it's rich and lovely, but it's hard to tweak, e.g. what if I merely want to add an additional class element on the top nav tag to make the menu transparent, or sticky, etc?

Like you say, everywhere else quarto is really extensible and theme-able. but in most static site generators we also have control over things like how nav links from the quarto.yml get mapped to nav menus on the page. And it's already all there in the 20-odd website EJS templates (nearly all nav-related TBH), but modifying those templates in small ways is the one part that seems out of reach. (we can hack a bit with css or js but it's difficult without being able to add any custom classes to the html elements).

[jimjam-slam]

That makes sense, @cboettig!

[sebastian-ruiz]

I found that I can pass a custom template. For example on the about page I can do (at least as of v1.4.520):

about:
  template: custom/_customabout.ejs.html

however, I can't add custom properties to the page. I can't do:

about:
  some_custom_attribute: hello world!

This would be a nice feature that most static site generators have.

[wes-brooks]

My org is working to improve the accesibility of our workshops, which are rendered via quarto. We got a comment during a review that says it's confusing that there are three Landmarks on the page all called "navigation" (see picture). For reference these are the sidebar, table of contents, and "page-navigation" (prev/next buttons in the footer).

We'd like to be able to customize these <nav> elements by adding the aria-label attribute of the page to provide additional context that differentiates these three navigation areas for users who rely on screen readers. We were able to use a partial template to override the built-in toc.html, but sidebar and page-navigation come from EJS templates so for now we cannot customize those <nav> elements. I'd appreciate the Posit team implementing a system like the partial template system, but for EJS templates.

[mcanouil]

@wes-brooks This is unrelated to the request in this thread.
Please open an issue for this, so the accessibility is tracked properly: https://github.com/quarto-dev/quarto-cli/issues/new?template=bug_report.yml

[wes-brooks]

@mcanouli I disagree that my comment is off topic. I want to contribute to discussion of the feature request that users be able to customize the EJS templates, or to override the defaults with customized templates.

[mcanouil]

You have issue about accessibility which impact the current state of a website regardless of how it could possibly be customised in the future.
This a "now" concern.
Customisation is not a tool to fix accessibility issues.
So could you open an issue to file this accessibility issue in order for it to get fixed?

[wes-brooks]

Even if our specific case is considered a "now" issue, it is still relevant to this general discussion of customizing EJS templates, yes?

[mcanouil]

Could you at least reply in the same thread within the discussion?

[mcanouil]

To be clear, the discussion is not really about EJS listing templates which you can already customised.
It's about allowing the other pieces of the website to be customised using a similar logic.

Again, if the base default structure is fixed regarding accessibility, then any work to extend customisation will of course rely on the fix and not regress on this aspect at least on purpose.

In another word, I'm asking you to file a bug report to help the team fix the accessibility issue rather than asking the team to work on a feature to work around the accessibility issue.