[HTML] add media embeding example as natively supported by Pandoc

[cderv]

What would you like to do?

Give feedback or suggest an improvement

Description

Pandoc supports for Image syntax ![](media), a mimetype guesser which will in HTML use audio, video or embed tag. https://github.com/jgm/pandoc/blob/8613aa39e8b5b8282f30b9fd48b04ec2595ec8eb/src/Text/Pandoc/Writers/HTML.hs#L1589-L1594

We could document this syntax better as it is hard to find and know. We could also link from there to video shortcode (https://quarto.org/docs/authoring/videos.html) as a better solution.

Some extensions exists for this already:

• https://github.com/jmgirard/embedpdf
• https://github.com/coatless-quarto/embedio

We don't have great PDF embedding built-in yet too, and we can maybe provide something better than default one. 🤔 I'll open an issue maybe keep track of the idea and get votes.

[mcanouil]

The syntax also supports PDF and will display viewer when available in the browser.

• https://github.com/quarto-dev/quarto-cli/discussions/10177
• https://github.com/quarto-dev/quarto-cli/discussions/5863

For instance you can even do advanced thing for the PDF viewer:

![](slides-lec2.pdf#zoom=90&&navpanes=0&statusbar=0&messages=0&pagemode=none){width=100% height=475px}

Source: https://github.com/quarto-dev/quarto-cli/discussions/5863#discussioncomment-8946109

I'm not sure @coatless and @jmgirard knew about this native Pandoc feature/syntax for embedding PDF.

[jmgirard]

The fact that we didn't know about this is probably evidence that the enhanced Quarto documentation is needed. I think this feature largely obviates the need for my extension. One thing my extension does add, however, that I'm not sure pandoc supports is the ability to provide a "fallback" image and download link in case the PDF rendering fails. Something like this built into Quarto/pandoc would be helpful.

[mcanouil]

I think the syntax supports the preview image attribute. (I don't have an example right now though)

[cderv]

The syntax also supports PDF and will display viewer when available in the browser.

Yes it is using embed html5 tag

> quarto pandoc --to html
![](index.pdf)
^Z
<p><embed src="index.pdf" /></p>

It is a generic tag https://developer.mozilla.org/en-US/docs/Web/HTML/Element/embed

I think this feature largely obviates the need for my extension.

Your extension is using a Javascript library right ? The built in pandoc feature is nice, but it probably as way less feature that you can do in an extension targetting a specific JS pdf viewer.

If we build the feature inside quarto, this would be to provide

• Nicer default for HTML embedding
• Fallback for different format.

One thing my extension does add, however, that I'm not sure pandoc supports is the ability to provide a "fallback" image and download link in case the PDF rendering fails.

Pandoc only does something with it for HTML output format. For other format, I guess it will just try to use the file as an image of format pdf.

This issue is about documenting the existing syntax specific to HTML. For a built-in feature, it needs to be discussed in another issue. Thanks

[jmgirard]

I'll just note that the pandoc approach is really nice in that it makes it very easy to embed the PDF file into a standalone HTML file (if desired). This is more difficult in the extension approach. So the quarto version should (obviously) keep this functionality and the documentation should probably mention this.

[coatless]

I'm all for building/documenting more of these features. Going through an extension system to access it, requires knowing that the extension exists; which is a fun discoverability problem.

It would be nice for Quarto to have a similar repo and rendered website that mirrored Yihui's knitr-examples.

[mcanouil]

You mean: https://github.com/quarto-dev/quarto-examples

[coatless]

@mcanouil discoverability 😉 (ducks)

[cderv]

It would be nice for Quarto to have a similar repo and rendered website that mirrored Yihui's

The discussion have drift way from original issue - it would have been best to open a new discussion for this idea. 😉 Let me take the opportunity to add some notes on that, as the previous answer is a bit short.

knitr-examples is a repo for testing features. It serve as example, but main purpose is testing feature by adding small example document that we don't want to break. This repo would not contain example of external feature to knitr. I am taking the parallel as I am not sure we would document Pandoc's own behavior in such repo.

Equivalent of knitr-examples for Quarto is more the current test suites, and the new feature format matrix we are currently building. Like knitr-example, everything is in github repo form right now

• Lots of documents with very small feature-target example that we test at each commit: https://github.com/quarto-dev/quarto-cli/tree/main/tests/docs/smoke-all. This is mainly test purpose and we don't plan to have a rendered website, or more extensive documentation on this content. Though, we'll mention this in our future dev-doc for sure.

• New feature-format matrix ongoing work (and still undocumented) lives in https://github.com/quarto-dev/quarto-cli/tree/main/dev-docs/feature-format-matrix. First purpose here is documentation of what is supported by each format, with a way for us to know which format is missing which support. Those examples can be tested easily (and we do it already), and they can also be presented publicly in a nicer way than a git repo. This is sill under going work, but there will be summary of support and a way to see rendered document. It requires time and time is rare (usual challenge !)

• quarto-dev/quarto-examples is a repo to store common example we encountered in Discussion or issues. Some question that come up often and so could end up in a place easy to refer. Only purpose is documentation presented at : https://examples.quarto.pub/ Those example can be way larger that in the previous two cases - the idea is to be able to show use case that present how tools can integrate all together, so it is not just about Quarto own feature. An example about various way to embed media could easily live there showing build it way, and also nice extension. Same challenge, it takes time to build efficient example to show there. But this is a different repo so that it is easy to accept contributed example there, even if it is meant to be an addition to existing gallery on the main website. This idea off having a place to store all examples is still ongoing - it is a repo today, could be a whole org for more complex examples (but this one is still empty).

Hope this answer can serve to clarify the current situation - TBH we are focusing on first one (good tests), and second one (ff-matrix), and currently don't spend much time on quarto-examples. This hopefully will change in the future.

Regarding discoverability, I hope @mcanouil work on https://github.com/mcanouil/awesome-quarto (and maybe its associated website 😉 ) are helpful ! In general, discoverability of everything existing thing in an ecosystem is a hard part of any project !