What's the correct way to add html/site assets via an extension?

[astroDimitrios]

Description

I'm making an extension and adding css works fine via the css: yml entry but what is the correct way of adding images, favicons, js?

If I use format-resources then folders with my assets appear to be copied into every directory where I've specified .md files to render which means lots of duplication of images and javascript. Is there a way to copy them as site wide assets via the extension?

My current _extension.yml and an example website repo structure where there are files to render in episodes, instructors, learners etc.

[mcanouil]

If I use format-resources' then folders with my assets appear to be copied into every directory where I've specified .md` files to render which means lots of duplication of images and javascript.

Did you read the documentation on creating extensions?
https://quarto.org/docs/extensions/formats.html#format-resources

Is there a way to copy them as site wide assets via the extension?

Again, I am directing you to the documentation: https://quarto.org/docs/extensions/lua-api.html

[astroDimitrios]

Ok thanks :) - so it looks like I need the Quarto Lua API (quarto.doc.add_html_dependency()). Is it worth adding anything to this section of the docs along the lines of: this call allows you to add site wide resources to the site_libs directory, and perhaps something about the directory structure of added resources?

For instance I added:

quarto.doc.add_html_dependency({
    name = "carpentries-images",
    version = "1.0.0",
    resources = {"images"}
  })

which means I now have access to these images in _site/site_libs/quarto-contrib/carpentries-images-1.0.0/images.

Now just need to work out how to add this path to my metadata with the lua so I don't have to type it out all the time!

[cderv]

You have also quarto.doc.add_format_resource(path) is this is easier to have the resource as part of the project from content shipped inside the extension.

Regarding Path, quarto.utils.resolve_path(path) could be helpful to compute path internally to your extension.

[rossbowen]

I have arrived here after looking for some similar advice. One thing I am unsure of is in what instances it would be best to use quarto.doc.add_html_dependency and to specify resources as opposed to using quarto.doc.add_format_resource.

I am trying to add a favicon and other assets. I attempted this using quarto.doc.add_html_dependency because that worked well for including CSS and JS, but for other resources I would need to do some wrangling of paths to get my template pointed to the correct resource location (I think as @astroDimitrios mentions above).

It seems like the expected thing to do here is to use quarto.doc.add_format_resource and then reference the resources as if those assets are in the top level directory alongside the output document.

[rossbowen]

I originally attempted to add the assets using quarto.doc.add_html_dependency(resources = {}).

Though I have just realised that this gets me close:

quarto.doc.add_html_dependency({
  name = "favicon",
  version = "0.1.0",
  resources = { "assets/images/favicon.ico" },
  links = {
    {
      rel = "icon",
      href = "/assets/images/favicon.ico"
    }
  }
})

Unfortunately the resulting HTML either gives an absolute path or a relative path like

<link href="/assets/images/favicon.ico" rel="icon">

but the resulting files aren't there, they are located at example_files/libs/quarto-contrib/favicon-0.1.0/favicon.ico, so I guess the HTML I am targeting, given a Quarto document example.qmd, is:

<link href="example_files/libs/quarto-contrib/favicon-0.1.0/favicon.ico" rel="icon">

[mcanouil]

@rossbowen quarto.doc.add_html_dependency is to add HTML resources into a "namespace" composed of "name" and "version", so everything you list in it won't be at the root.

I suggest you read the documentation about the API you mentioned to understand what they are for: https://quarto.org/docs/extensions/lua-api.html#quarto-lua-api

Depending on what is your extension, you can contribute assets, for instance for website: https://quarto.org/docs/websites/website-tools.html#site-resources

Instead of hardcoding the path as you do, you could resolve it using Quarto API to ensure it points to the right location regardless of how your extension was installed: quarto.utils.resolve_path(path).

For more, you need to provide a concrete small example to work with.

[rossbowen]

Thank you @mcanouil!

It is difficult to apply the documentation.

I am creating a custom format for HTML. I see from this documentation I could provide format-resources, so setting the following in my _extension.yml:

contributes:
  formats:
    html:
      toc: true
      theme: [yeti, custom.scss]
      format-resources: ["favicon.ico"]

This will make a copy of favicon.ico that sits alongside my Quarto document.

I think I could combine this with a lua filter:

quarto.doc.add_html_dependency({
  links = {
    {
      rel = "icon",
      href = "/favicon.ico"
    }
  }
})

This is one way to achieve what I hope to, but I have a lot of resources that I want to include: a lot of difference sized favicons, and also some custom CSS and javascripts. These would end up getting copied alongside each Quarto document whenever a user goes to render anything, and would really clutter their folders and possibly conflict with other files. So I don't think this presents a good experience to the user.

Attempting to do it with quarto.doc.add_html_dependency, I've got a small example here.

-- Using scripts works wonderfully.
-- The output HTML includes a reference to a copy of the script inside the
-- template_files directory.

quarto.doc.add_html_dependency({
	name = "example-js",
	scripts = { "example.js" },
})

-- resources does not behave in the same way.

-- href = "favicon.ico" copies the favicon into the template_files directory,
-- but the link added to the output uses an absolute reference to the incorrect
-- location.

-- This suggests I need to change the href.

-- I have tried a relative path href = "./favicon2.ico". The link here would
-- work if combined with the `format-resources` option in _extension.yml, but it
-- does not work when combined with the resources option in add_html_dependency.

-- I have also tried using quarto.utils.resolve_path(). This returns an absolute
-- path to the file, and this time uses the location of the file within the
-- _extensions directory. Absolute paths do not feel like the right solution.

quarto.doc.add_html_dependency({
	name = "favicon",
	resources = {
		{ name = "favicon.ico", path = "favicon.ico" },
		{ name = "favicon2.ico", path = "favicon2.ico" },
		{ name = "favicon3.ico", path = "favicon3.ico" },
	},
	links = {
		{
			rel = "icon",
			href = "favicon.ico",
		},
		{
			rel = "icon",
			href = "/favicon2.ico",
		},
		{
			rel = "icon",
			href = quarto.utils.resolve_path("favicon3.ico"),
		},
	},
})

The outcome I'd hope for is to see the following in the head of the document:

<link href="template_files/libs/quarto-contrib/favicon/favicon.ico" rel="icon">

Finally, looking at the HTML dependencies documentation, I noticed two things. It says for links:

List of link tags to add to the document. Each tag should be a table with rel and ref.

But it actually wants href instead of ref.
It also claims version is required but that was not my experience.