From fdbf1f63b97a28f2de96442df586cf8da1a985d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micka=C3=ABl=20Canouil?=
 <8896044+mcanouil@users.noreply.github.com>
Date: Sun, 1 Jun 2025 17:59:22 +0200
Subject: [PATCH 1/2] docs: improve custom listing documentation

---
 docs/websites/website-listings-custom.qmd | 38 ++++++++++++++++++-----
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/docs/websites/website-listings-custom.qmd b/docs/websites/website-listings-custom.qmd
index 47667ee805..262923e172 100644
--- a/docs/websites/website-listings-custom.qmd
+++ b/docs/websites/website-listings-custom.qmd
@@ -8,8 +8,7 @@ In addition to the 3 built in types of listings, you can also build a completely
 
 ## Listing Templates
 
-To build a custom listing display, you create an [EJS template](https://ejs.co) that will be used to generate the HTML for a set of items that are passed to the template. EJS templates allow you to generate HTML using plain javascript, making it easy to loop through items and output their values in your custom HTML.
-
+To build a custom listing display, you create an [EJS template](https://ejs.co) that will be used to generate the HTML for a set of items that are passed to the template. EJS templates allow you to generate HTML using plain JavaScript, making it easy to loop through items and output their values in your custom HTML.
 
 To use a custom template, pass it in the `template` option for a listing:
 
@@ -26,15 +25,17 @@ listing:
   template: gallery.ejs
 ```
 
-A simple template for outputing a list of documents might look like:
+A simple template for outputting a list of documents might look like:
 
-``` html
+````markdown
+```{=html}
 <ul>
 <% for (const item of items) { %>
   <li><a href="<%- item.path %>"><%= item.title %></a></li>
 <% } %>
 </ul>
 ```
+````
 
 which produces simple HTML output like:
 
@@ -42,6 +43,22 @@ which produces simple HTML output like:
 
 When rendered, the above template will receive an array of listing items called `items`. When the contents of a listing are loaded from a list of documents, each of those items will be populated with the fields described in [Listing Fields](website-listings.qmd#listing-fields). In addition, any other fields included in a documents metadata will be passed as a property of the item, making it possible to use custom metadata in your documents and the listing display.
 
+Because the EJS templates are processed by Quarto, the templates are intrinsically Markdown documents.
+For example, if you want your listing `title` (*e.g.*, `My **bold** title`) to support Markdown formatting, you need to change the above simple template into:
+
+````markdown
+```{=html}
+<ul>
+<% for (const item of items) { %>
+  <li><a href="<%- item.path %>">
+```
+<%= item.title %>
+```{=html}</a></li>
+<% } %>
+</ul>
+```
+````
+
 ::: {.callout-note}
 
 Note that Quarto uses `lodash` to render the EJS templates. The `lodash` uses different syntax for HTML escaping text in templates. 
@@ -71,7 +88,7 @@ listing:
 
 could be rendered using:
 
-```` html
+````markdown
 ```{=html}
 <ul>
 <% for (const item of items) { %>
@@ -134,7 +151,8 @@ By default, sorting, filtering, and pagination are disabled for custom listings
 
 For example, we can modify the above `custom.ejs` template as follows:
 
-``` html
+````markdown
+```{=html}
 <ul class="list">
 <% for (const item of items) { %>
   <li <%= metadataAttrs(item) %>>
@@ -144,6 +162,7 @@ For example, we can modify the above `custom.ejs` template as follows:
 <% } %>
 </ul>
 ```
+````
 
 Once you have included these items in your template, you can then enable the options in your listing:
 
@@ -218,8 +237,10 @@ listing:
 
 Template parameters can then be accessed in your template using `<%= templateParams.param1 %>`. For example, we can modify the above `custom.ejs` template as follows:
 
-``` html
-<h3><%= templateParams.param1 %></h3>
+````markdown
+### <%= templateParams.param1 %>
+
+```{=html}
 <ul class="pub-list list">
   <% for (const item of items) { %>
       <li <%= metadataAttrs(item) %>>
@@ -228,3 +249,4 @@ Template parameters can then be accessed in your template using `<%= templatePar
   <% } %>
 </ul>
 ```
+````

From 17658c4a9dc0e5a13eed481117df27e384adc5ac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micka=C3=ABl=20Canouil?=
 <8896044+mcanouil@users.noreply.github.com>
Date: Sun, 1 Jun 2025 18:02:43 +0200
Subject: [PATCH 2/2] docs: add note about gallery listing example

---
 docs/websites/website-listings-custom.qmd | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/websites/website-listings-custom.qmd b/docs/websites/website-listings-custom.qmd
index 262923e172..98aca78353 100644
--- a/docs/websites/website-listings-custom.qmd
+++ b/docs/websites/website-listings-custom.qmd
@@ -132,13 +132,17 @@ where the contents of `items.yml` is:
 Portions of this website are built using custom listings. The best place to start is with [our gallery](/docs/gallery/index.qmd), which is a listing built using a custom template and a metadata file. You can view the source code used to create the gallery page in our [Github repository](https://github.com/quarto-dev/quarto-web).
 
 | File                                                                                       | Description                                                                          |
-|-------------------------------------|-----------------------------------|
+|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
 | [gallery.yml](https://github.com/quarto-dev/quarto-web/blob/main/docs/gallery/gallery.yml) | The metadata that controls what items are displayed in the gallery listing.          |
 | [gallery.ejs](https://github.com/quarto-dev/quarto-web/blob/main/docs/gallery/gallery.ejs) | The template used to display the items on the page.                                  |
 | [index.qmd](https://github.com/quarto-dev/quarto-web/blob/main/docs/gallery/index.qmd)     | The Quarto document that configures and positions the listing in the `#gallery` div. |
 
 : {tbl-colwidths="\[30,70\]"}
 
+::: {.callout-note}
+Note that the `gallery.ejs` template does not allow its content to be read as Markdown.
+:::
+
 ## Sorting, Filtering, and Pagination
 
 By default, sorting, filtering, and pagination are disabled for custom listings templates, but with some simple changes to your template and listing options, you can add this capability to your custom listing. To do this, you need to include the following three things in your custom template: