Ability to set the base URL for formats other than HTML?

[sun123zxy]

Description

In a website project we have the metadata site-url to indicate the base URL of the site. This is well implemented in the HTML format, but it would be useful to have a similar feature for other formats like PDF.

For a use case, consider a website project with PDF versions of the content. PDF files are intended to be downloaded and viewed offline, but without a base URL, the relative links in the PDF files point to local file paths, which is clearly not what we want. More generally, it calls for an option to set the base URL for an independent document, not necessarily by site-url, which is only available in a website project.

To the best of my knowledge, there's no built-in way to set a base URL for formats other than HTML in Quarto. Actually this had been discussed in a Pandoc Issue, though currently there're only manmade Lua filter resolutions. Speaking of site-url, it's also awkward for Lua filter to workaround, because Quarto's project metadata is not passed to the Pandoc context.

It would be nice if above is supported by Quarto in some form. Correct me if I'm missing something obvious. Thanks!

[cderv]

PDF files are intended to be downloaded and viewed offline, but without a base URL, the relative links in the PDF files point to local file paths,

Can you detail what you mean? What local file paths exactly? Using a Quarto Website, if you include a PDF, it will be downloadable from a URL that includes the site URL.

For example Lua quick reference guide linked from https://quarto.org/docs/extensions/lua.html
The link is : https://quarto.org/docs/extensions/luarefv51.pdf

More generally, it calls for an option to set the base URL for an independent document, not necessarily by site-url, which is only available in a website project.

site_url is only used in a website project because this is the format for organizing content together, and some features require a site URL.

A link to the document deployed in the same folder or nested folder is usually relatively included, and the site URL where the document is deployed will be used.

To the best of my knowledge, there's no built-in way to set a base URL for formats other than HTML in Quarto. Actually this had been discussed in jgm/pandoc#4894, though currently there're only manmade Lua filter resolutions.

I see the pandoc issue is discussing root path for image. Is that the use case for site-url for single document ?
Syntax like ![](/image.png) is already resolved by Quarto as the root of the Quarto project, and should be made relative link to project root. So when using output-dir, relative to output directory root.

Speaking of site-url, it's also awkward for Lua filter to workaround, because Quarto's project metadata is not passed to the Pandoc context.

Some metadata are passed. website config may not. I think there is a feature request about this.

It would be nice if above is supported by Quarto in some form. Correct me if I'm missing something obvious. Thanks!

It would really help us if you can share a real case example of site-url like feature for single document publishing is required. Could you ?

Thank you !

[sun123zxy]

Can you detail what you mean? What local file paths exactly? Using a Quarto Website, if you include a PDF, it will be downloadable from a URL that includes the site URL.

Sure! There might be some misunderstanding so I've made a minimal demo site to make it clear. The source code can be found at sun123zxy/quarto-discussion-13000.

The actual case here is to provide both a web page version and a PDF version of a QMD file in a website project, that is, having both html and pdf turned on in the format option.

In the index page of the demo site, there are two links and an image. The first link is [...](index.qmd), the second link is [...](index.html), the image is ![...](image.png). Experiment with the two links in the index page in different environments:

• In the web page:

  • Both links work well (linking to https://sun123zxy.github.io/quarto-discussion-13000/about.html)
  • The image works well.

• Download the index page and open it locally:

  • Both links work well.
  • The image works well.

• Open the PDF (located in the other formats panel on the right side) directly in the browser:

  • The first one links to https://sun123zxy.github.io/quarto-discussion-13000/about.qmd, which actually does not exists on the server.
  • The second one works well.
  • The image works well.

• Download the PDF and open it locally:

  • Both links get invalid.
  • The image works well.

Above shows that in a website project, links in the formats other than HTML are not handled identically with those in HTML --- not prefixed by a base URL (thus referring to local file path), and no special treatment for links to .qmd. That's what I was calling for in the previous post. Images seem to be OK, though.

I see the pandoc issue is discussing root path for image. Is that the use case for site-url for single document ?
Syntax like is already resolved by Quarto as the root of the Quarto project, and should be made relative link to project root. So when using output-dir, relative to output directory root.

Maybe that's why images work well in the above demo? Note that this Pandoc issue is also discussing the root path for links.

It would really help us if you can share a real case example of site-url like feature for single document publishing is required. Could you ?

Regrettably I haven't really come up with a specific use case. I thought this was somehow an intermediate step to resolve the above issue. If it is not, feel free to ignore this :)

Thank you for your time!

[mcanouil]

@sun123zxy

(in this case, the base url will be missing)

[mcanouil]

Note that you can still use a Lua filter.

• Dead links in PDF of quarto website. #12394 (reply in thread)

[sun123zxy]

Note that you can still use a Lua filter.

@mcanouil I see, this would be a workaround for this. I notice that this discussion is about a book project. Ideally for a website project we can use site-url to indicate the base URL. But currently it is not accessible in a Lua filter.

[mcanouil]

Books are websites.

[mcanouil]

I agree that having access to the project metadata would be great and not only in this context.

For instance, retrieving the repo-url would be great for projects as it would avoid having to set an extra key for my "GitHub" extension.