Are the EJS files for included listing styles available for adaptation?

[petrbouchal]

Description

I would like to adapt the listings included in Quarto - default, table, grid.

Ideally I would take the EJS that produces the equivalent to what Quarto produces out of the box and adapt the EJS template.

I wasn't able to find the EJS files in the repo - did I miss something or are the listings produced in some other way?

If the latter, would it be possible to include the "equivalent" EJS files in the repo or in the documentation?

[dragonstyle]

They are generated via EJS and can be found here:

https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/projects/website/listing

They can be a little hard to adapt as they have a lot support for options and other conditions (which typically custom styles wouldn't need to support). They can provide a started but if they're hard to navigate, feel free to ask and we can try to provide some pointers or simpler examples.

Here is a recent example I provided of a very simple version of something closer to our 'default' style listing:

<div class="list quarto-listing-default">
<% for (const item of items) { %>

<div class="quarto-post image-<%= imageAlign %>" <%= listing.utilities.metadataAttrs(item) %>>
    <div class="thumbnail">
        <a href="<%- item.path %>">
        <!-- preview image tag here -->
        </a>
    </a>
    </div>
    <div class="body">
        <a href="<%- item.path %>">
        <h3 class="no-anchor listing-title"><%= item.title %></h3>
        <div class="listing-subtitle"><%= item.subtitle %></div>
        </a>
        <div class="listing-categories">
        <% for (const category of item.categories) { %>
        <div class="listing-category" onclick="window.quartoListingCategory('<%=category%>'); return false;"><%= category %></div>
        <% } %>
        </div>
        <a href="<%- item.path %>">
        <div class="delink listing-description">
            <%= item.description %>
        </div>
        </a>
    </div>
    <div class="metadata">
        <a href="<%- item.path %>">
            <!-- meta stuff here -->
        </a>
    </div>
</div>

<% } %>
</div>

[petrbouchal]

Thanks, that's very helpful!

[emilyriederer]

@dragonstyle - could you provide any context why the official Quarto versions are saved as .ejs.md files and what the pros/cons are? The docs for the custom versions and most examples just use .ejs. I'm working on a custom listing and struggling to understand the difference.

Seconding @petrbouchal - thanks for the simplified "default"! I'm trying to make minor tweaks that will look consistent with places where I'm using the default so it's a great lauchpad.

[dragonstyle]

could you provide any context why the official Quarto versions are saved as .ejs.md files and what the pros/cons are?

This is merely a convention we have to help us understand what format the compiled EJS is expected to produce (md in this case). It has no bearing on the behavior of EJS and doesn't have any other effects- using .ejs is just fine.

[emilyriederer]

Also @dragonstyle - could you please give an example of how to call your example from a listing configuation?

I tried saving that file as talk.ejs fenced in ```{=html} per the customization examples. This is saved in the same directory as my index.qmd. In said index, if I change from:

type: default

to

template: talk.ejs

I get the error:

listing is not defined

which seems to refer the the listing variable used in the ejs

[dragonstyle]

Sorry about the error - I had just quickly written out the pseudo code without testing it. This template works just fine in my local tests:

```{=html}
<div class="list quarto-listing-default">
    <% for (const item of items) { %>
    
    <div class="quarto-post <%= metadataAttrs(item) %>>
        <div class="thumbnail">
            <a href="<%- item.path %>">
            <!-- preview image tag here -->
            </a>
        </a>
        </div>
        <div class="body">
            <a href="<%- item.path %>">
            <h3 class="no-anchor listing-title"><%= item.title %></h3>
            <div class="listing-subtitle"><%= item.subtitle %></div>
            </a>
            <div class="listing-categories">
            <% for (const category of item.categories) { %>
            <div class="listing-category" onclick="window.quartoListingCategory('<%=category%>'); return false;"><%= category %></div>
            <% } %>
            </div>
            <a href="<%- item.path %>">
            <div class="delink listing-description">
                <%= item.description %>
            </div>
            </a>
        </div>
        <div class="metadata">
            <a href="<%- item.path %>">
                <!-- meta stuff here -->
            </a>
        </div>
    </div>
    
<% } %>
</div>
```

[emilyriederer]

Thank you so much! Appreciate this!

[emilyriederer]

@dragonstyle - Could I please ask you one more question on this? Since this example sets all the same IDs / classes as the default, I was hoping it would pick up the same styling from the CSS (e.g. for categories). However, trying this listing, that doesn't seem to be the case. Is there any intuition you can share on that? I see the .scss file in the same dir, but I'm trying to fork as little as possible so any modifications I make should play nice in the longterm

[mcanouil]

Most of the styling is done internally and is not really exported if I am not mistaken.
So you need to replicate it I believe.

[dragonstyle]

I would've expected the css style to work with this (no need to involve the scss file, the styles are included in the bootstrap theme(s) used by Quarto). We don't really make guarantees about the structure of HTML / CSS, so YMMV may vary trying to reproduce it, but I'm not sure why it isn't working...