Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: Markdown support in listings templates #11760

Open
wants to merge 14 commits into
base: main
Choose a base branch
from

Conversation

mcanouil
Copy link
Collaborator

@mcanouil mcanouil commented Dec 30, 2024

The changes restore Markdown support in the default listings templates after the introduction of {=html} in version 1.7.5. This update ensures that Markdown formatting is correctly rendered in listings.

Fixes #11758.

This PR also adds a check for subtitle field in the default listing. Previously it was adding subtitle even when not provided as long as title was.

Tested on: https://m.canouil.dev/quarto-issues-experiments/issue11758/
Source: https://github.com/mcanouil/quarto-issues-experiments/tree/main/quarto-cli-11758

To do:

@mcanouil mcanouil self-assigned this Dec 30, 2024
@mcanouil mcanouil changed the title fix:Markdown support in listings templates fix: Markdown support in listings templates Dec 30, 2024
Copy link
Collaborator

@cderv cderv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot !

Using raw inlines for each raw HTML seems the right call if we need to avoid markdown in HTML parsing.

Only impact I can think of is that <div> in markdown leads to Div in AST, while using raw inline leads to RawInline. It has impact on Lua filter processing.

❯ pandoc -t native
<div class="thumbnail">**STRONG**</div>
^Z
[ Div
    ( "" , [ "thumbnail" ] , [] )
    [ Plain [ Strong [ Str "STRONG" ] ] ]
]

~ took 12s
❯ pandoc -t native
`<div class="thumbnail">`{=html}**STRONG**`</div>`{=html}
^Z
[ Para
    [ RawInline (Format "html") "<div class=\"thumbnail\">"
    , Strong [ Str "STRONG" ]
    , RawInline (Format "html") "</div>"
    ]
]

So we probably need to make sure we have no Lua processing applying on any Div we create in Listing. I check our Lua code using search.

See more in comment about some example of potential issue - I think we are safe as they seems to apply in Dashboard format only.

Regarding test, it seems something needs to be adapted as a test seems to be broken. Didn't look carefully yet.

Thanks again for the PR !

@mcanouil
Copy link
Collaborator Author

mcanouil commented Jan 2, 2025

I'm a bit stuck for the remaining raw HTML code.

Using the following without raw code block works as expected for having the item being read/evaluated as markdown.

<h5 class="no-anchor card-title listing-title"><%= item.title %></h5>

Using raw block will lead to the item being placed in a <p> tag leading to extra styling which is really unwanted inside h5.

```{=html}
<h5 class="no-anchor card-title listing-title">
```
<%= item.title %>
```{=html}
</h5>
```
```

This happens for other parts with `<div>` (grid and default listings) and `<td>` (table listing and grid listing for metadata).

Margins added by `<p>` could be dealt with (S)CSS but it's a bit messy.

Any ideas?

Comment on lines 87 to 89
```
<%= outputValue(itemNumber, field) %>
```{=html}
Copy link
Collaborator Author

@mcanouil mcanouil Jan 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This leads to extra <p> being added as the line is read as Markdown.

image

Copy link
Collaborator Author

@mcanouil mcanouil Jan 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

refactor a bit by making <td> outside the raw block.

9c43d63

::: {.card-body .post-contents}

<% if (showField('title')) { %>
<h5 class="no-anchor card-title listing-title"><%= item.title %></h5>
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No raw block to avoid <p> being added.

<% } %>

<% if (showField('subtitle')) { %>
<div class="card-subtitle listing-subtitle"><%= item.subtitle %></div>
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No raw block to avoid <p> being added.

```

<% if (showField('author')) { %>
<div class="listing-author"><%= item.author %></div>
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No raw block to avoid <p> being added.

<% } %>

<% if (showField('date')) { %>
<div class="listing-date"><%= item.date %></div>
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No raw block to avoid <p> being added.

Comment on lines 58 to 60
<h3 class="no-anchor listing-title"><a href="<%- item.path %>" class="no-external"><%= item.title %></a></h3>
<% if (fields.includes('subtitle')) { %>
<div class="listing-subtitle"><a href="<%- item.path %>" class="no-external"><%= item.subtitle %></a></div>
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No raw block to avoid <p> being added.

Comment on lines +98 to +104
<% if (fields.includes('date') && item.date) { %>
<div class="listing-date"><%= item.date %></div>
<% } %>

<% if (fields.includes('author') && item.author) { %>
<div class="listing-author"><%= item.author %></div>
<% } %>
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No raw block to avoid <p> being added.

Comment on lines 138 to 149
```{=html}
<table class="card-other-values">
<% for (const field of otherFields) {
let value = readField(item, field);
<% for (const field of otherFields) {
let value = readField(item, field);
%>
<tr>
<td><%= listing.utilities.fieldName(field) %></td>
<td class="<%-field%>"><%= listing.utilities.outputLink(item, field, value) %></td>
<td class="<%- field %>"><%= listing.utilities.outputLink(item, field, value) %></td>
</tr>
<% } %>
</table>
```
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No markdown supports in metadata with this.
Splitting this to allow markdown for listing.utilities.fieldName(field) and listing.utilities.outputLink(item, field, value) will lead to <p> being added.

Copy link
Collaborator Author

@mcanouil mcanouil Jan 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For consistency until there is a decision, I switched to using raw blocks except for the lines with the variables to allow markdown.

9c43d63

This means, there is still inline HTML.

@mcanouil
Copy link
Collaborator Author

mcanouil commented Jan 2, 2025

In the current state, I have a constant normal memory consumption when rendering the project from #11701

Still need to check the failing test: https://github.com/quarto-dev/quarto-cli/actions/runs/12582608380/job/35068595360?pr=11760
Edit: I don't understand what's the issue or what's being tested as the listing (tests/docs/listings) renders and works properly from what I have seen.
This listing test could be updated to include markdown in title/subtitle/description.
Edit2: seems to be good now

@mcanouil mcanouil added the needs-discussion Issues that require a team-wide discussion before proceeding further label Jan 2, 2025
@mcanouil mcanouil marked this pull request as ready for review January 2, 2025 16:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
needs-discussion Issues that require a team-wide discussion before proceeding further
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Markdown is no longer supported in listings (>= 1.7.5)
2 participants