Markdown images are an anti-pattern

[baptiste]

Description

I found this recent blogpost quite convincing: it makes the case that

<img src="example.jpg" 
     alt="descriptive text goes here" 
     height="400" 
     width="300" 
     decoding="async"
     loading="lazy">

is in fact more legible, and better altogether than

![descriptive text goes here](example.jpg){: height="36px" width="36px" decoding="async" loading="lazy" }

I wonder, following Quarto v1.3's adoption of html table input for all formats, if the same idea would make sense for images? Of course the original markdown syntax would stay, for simple cases and back-compatibility, but the <img> flavour would also be available as a more robust/descriptive alternative.

[mcanouil]

Then use the html markup when you are using HTML-based formats.
What more do you need?

Note that GitHub Flavoured Markdown does the same thing as Quarto/Pandoc and allows you to use markdown/html for images.

Your issue with Markdown being anti-pattern is wrong, because Markdown is not an alias for HTML code.
Markdown is used for example to create LaTeX PDF, i.e., it wouldn't make sense to use Markdown and HTML image tags to produce LaTeX code (even if kind of the case with tables).

In my opinion, it's not a good idea to mix markups languages which can lead to really weird behaviour or for user to expect impossible things.

See Quarto document code.

---
title: "Quarto Playground"
format: html
---

This is a playground for Quarto.


![A picture of an elephant](https://upload.wikimedia.org/wikipedia/commons/thumb/3/37/African_Bush_Elephant.jpg/1920px-African_Bush_Elephant.jpg){#fig-elephant1 width="200px" fig-alt="A picture of an elephant"}


::: {#fig-elephant2}

<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/37/African_Bush_Elephant.jpg/1920px-African_Bush_Elephant.jpg" alt="A picture of an elephant" width="200px" />

A picture of an elephant

:::

[cscheid]

I'm sympathetic to the readability argument, but I don't think the juice is worth the squeeze here.

Specifically, the 1.3 decision of parsing HTML tables comes from the fact that the native Pandoc Table AST element has features which are not actually supported by any of the native Markdown table input syntaxes. HTML input is really the cleanest way to consistently get features like rowspans, etc.

In the case of images, the argument is completely different, and Pandoc markdown already supports arbitrary attributes (though I think without the leading colon in your suggestion).

If we choose to support this feature, why would we then not support links? or other tags? I think the answer would be pretty unambiguously that it would make the overall Markdown reading experience of quarto documents worse.

The HTML table feature exists so that libraries can provide table inputs to Quarto that can still be processed by Lua filters; the IMG suggestion would either:

• add some immediate readability to one specific use case to the detriment of consistency of our design
• or make the design consistent to the detriment of document readability

That disjunction is negative for quarto on both sides, so I don't think it's a good feature to consider.

[baptiste]

That makes perfect sense; it's definitely always a trade-off between markdown's limitations and the goal of plain text readability. I agree that for tables the argument was different, and for images it's purely about readability, which is not enough (I just thought this was an interesting blog post to think about).

Thinking about it further, the {...} syntax for options only gets problematic when there are lots of arguments listed in it. With a format like Html, this can be circumvented by using CSS selectors: the image (or span, etc.) is given an id or a class, and any number of modifications can then be applied to it, without cluttering the source document. The same approach is more difficult in other formats like LaTeX, and I wonder to what extent this could be streamlined / encouraged a little more. One LaTeX-specific approach is the combination of latex-environment Lua filter with the definition of a custom \newcommand{} that does the equivalent of a CSS styling. A more versatile approach is to write a Lua filter that selects those images by id or similar identifier, and produces a custom transformed node in the AST. I wonder if something could be designed to make the process easier, and more "standardised": for example, there could be an equivalent of CSS directives, written either in the document's Yaml, or in a separate file, that the Lua filter picks up and automatically joins with the ID selectors from the document. To illustrate, the image example might become (for all formats):

![descriptive text goes here](example.jpg){id="elephant"}

and in a yaml field stored elsewhere:

elephant: 
   width: 30%;
   border: grey;
   decoding="async";
   loading="lazy";
   margin-top: 10px;

and the options not applicable to a given output format would simply be ignored.

(Note: the current syntax would still stay, this would only be an alternative, similar to the way SVG elements can be styled either with inline attributes or CSS)

[cscheid]

I believe you can implement that today with classes and Lua filters, but I don't know if it makes sense for us to do it as a first-class feature.

[mcanouil]

I agree that translating everything and making sure it's all work for all formats is a way too big endeavour to be undertaken by Quarto team, even Pandoc does not do that.

For an example of CSS/LaTeX colour attribute using a LUA filter: #5300

[baptiste]

Oh totally, I'm just brainstorming out loud here – wasn't suggesting this should be a core feature, as it'd be a lot of work to implement consistently everywhere. What I think could be useful and practical is to have an example of this approach as a reference somewhere.

[cderv]

@baptiste I think you can do what you described with a Lua filter, and package this as an extension for Quarto.

• Set id on images
• Have a YAML field for your extension like

  image-attr: 
      all: 
         loading: "lazy"
      elephant: 
   	   width: 30%
   	   border: grey
         decoding: "async"
   	   margin-top: 10px

• And then in Lua
  • Catch the metadata and store it in Lua
  • Use a Image filter to process images by getting the id, looking for matching metadata and set the attributes on the image

Having such extension would be a good way to show this and make it useful for those who needs it.