Pandoc: Add flag to set root path

[ad-si]

When converting markdown to another file format, it's common to use absolute URLs for images, as the HTML would load the Image from the root URL of the website.
However, Pandoc then tries to load them from the root path of the computer.
There should therefore be a flag to change the root path for Pandoc.

[jgm]

This is worth considering. For now I'd suggest using a lua filter to change the paths on all of your images.

[jgm]

Are you using the URL on the command line, or downloading the file and referencing it locally?
If you use the URL on the command line, pandoc will download the HTML and it will then know where to look to fetch resources that the page refers to.

[ad-si]

Locally. I guess that's the most simple example which doesn't work currently, but can be fixed with a --roth-path flag is:

$ ls
image.png index.md
$ cat index.md
![An image](/image.png)
$ pandoc index.md -o index.pdf
pandoc: /image.png: openBinaryFile: does not exist (No such file or directory)

[jgm]

Currently we handle two sorts of cases well:

(1) You want to convert a remote file, and you specify it with a URL on the command line. All resources will be fetched from the URL.
(2) You want to work locally, and you mirror the whole site -- the HTML (or md) files and their associated resources. All resources will be fetched locally.

It's not entirely clear to me what the motivation is for working on a file locally without mirroring the dependent resources, but that's the use case that would be covered by a --base-url or --root-path flag.

[ad-si]

I don't think I understand. I just gave you an example where I work locally, with all resources locally (i.e. the image.png file), but where the paths are absolute because the project will get hosted on an apex domain. So it's difference between being locally stored at e.g. ~/Projects/myproject and online at e.g. myproject.com

[jgm]

I don't think I understand. I just gave you an example where I work locally, with all resources locally (i.e. the image.png file), but where the paths are absolute because the project will get hosted on an apex domain. So it's difference between being locally stored at e.g. ~/Projects/myproject and online at e.g. myproject.com

OK, yes, that makes sense.

[priiduonu]

I would extend the use case.

When working locally with the files (or hosting them on a web server), relative paths can be used. When I produce a PDF, all relative paths (except images) do not work any more.

An example:
[a link to some subdir](subdir/) will not work from the PDF file (if the PDF file is opened from another computer).

By defining a --base-url or similar, pandoc could append the base url to the link automatically.
If I need to host the documentation on several web servers, all I need to do is just change the base-url for generating a PDF with working absolute links.

[mb21]

It's worth noting that this is somewhat tricky to get right in all cases. Jekyll, for example used to have a site.baseurl variable that was intended to be set to e.g. /mysite, but people misunderstood often and set it to http://example.com/... now, I think you're not supposed to use baseurl in your files, but the | absolute_url and | relative_url helpers.

Or would it be enough to have a --url-prefix option, that doesn't try to be smart but simply does string concatenation?

[priiduonu]

I think --url-prefix is a better name indeed. And if present, it should be prepended to relative links that are not a) image sources b) internal href anchors.

[jgm]

priiduonu [e-mail] writes:

I think --url-prefix is a better name indeed. And if present, it should be prepended to relative links that are not a) image sources b) internal href anchors.

I don't think we want to prepend to relative links in
general. A link like foo/bar should stay relative.
This should only affect a link like /foo/bar.
And yes, it should apply to image sources too.

[jaybe-jekyll]

Checking in about this root path idea/option. Presuming this has stalled and not been addressed?

I have been writing the logic/handling via make and it's so hacky.

Is there a lua example to smartly do this and or a better way?

[tarleb]

Lua-filter sketch:

function Image (img)
  if img.src:sub(1,1) == '/' then
    img.src = os.getenv 'WEBROOT' .. img.src
  end
  return img
end

This will prefix absolute image paths with the content of the WEBROOT environment variable.

[jaybe-jekyll]

Lua-filter sketch:

function Image (img)
  if img.src:sub(1,1) == '/' then
    img.src = os.getenv 'WEBROOT' .. img.src
  end
  return img
end

This will prefix absolute image paths with the content of the WEBROOT environment variable.

Thanks. Seeing the basic premise from your sketch.

How can we go about:

1. Adapting so all links may be affected; not just images?

2. Adapt so that pandoc variables/meta may be used versus and or in addition to environment variables?

[tarleb]

Using the webroot metadata field:

local webroot = ''
function Meta (meta) webroot = meta.webroot end
function fix_link (url) return url:sub(1,1) == '/' and webroot .. url or url end
function Link (link) link.target = fix_link(link.target); return link end
function Image (img) img.src = fix_link(img.src); return src end
return {{Meta = Meta}, {Link = Link, Image = Image}}

[jaybe-jekyll]

@tarleb -

Wanted to say thank you for your help and ideas in working a solution. I haven't implemented yet but looking forward to it. Thank you!

[NeoEGM]

Using the webroot metadata field:

local webroot = ''
function Meta (meta) webroot = meta.webroot end
function fix_link (url) return url:sub(1,1) == '/' and webroot .. url or url end
function Link (link) link.target = fix_link(link.target); return link end
function Image (img) img.src = fix_link(img.src); return src end
return {{Meta = Meta}, {Link = Link, Image = Image}}

Just for anyone falling here like me, there's a small bug in the Image function returning src and not img as it should.

Here it is fixed:

local webroot = ''
function Meta (meta) webroot = meta.webroot end
function fix_link (url) return url:sub(1,1) == '/' and webroot .. url or url end
function Link (link) link.target = fix_link(link.target); return link end
function Image (img) img.src = fix_link(img.src); return img end
return {{Meta = Meta}, {Link = Link, Image = Image}}

[tarleb]

The filter assumes that your image URLs start with a slash /. If that's not the case, and you'll need to modify the check in fix_link. This issue is not a good place to discuss this though, please reach out on the pandoc-discuss mailing list.