pandoc: How to link to a section in another markdown file?

Question

I would like to create two markdown files with links between their sections. The challenge here it's that I want the files to work correctly whether I ask pandic to concatenate them to a single HTML file, or to separate HTML files. The trouble is that in the latter case the link needs to know there name of the other HTML file in order to work properly.

It's there some way for pandoc to manage this without creating distinct versions of the markdown input?

Answer 1

The following uses Lua filters to fix your links. It assumes that links are written by prefixing them with the file in which the link is defined, for example [see here](some-other-file.md#topic). Some editors make it simple to switch to the respective file, so this can be an additional advantage.

When converting to multiple HTML files, all we need to do is replace the .md file extension in these links with .html.

-- fix-links-multiple-files.lua
function Link (link)
  link.target = link.target:gsub('(.+)%.md%#(.+)', '%1.html#%2')
  return link
end

Run it with

pandoc --lua-filter fix-links-multiple-files.lua file-1.md -o file-1.html

In the case of a single file, we can just drop the file part of the link:

-- fix-links-single-file.lua
function Link (link)
  link.target = link.target:gsub('.+%.md%#(.+)', '#%1')
  return link
end

Run with

pandoc --lua-filter fix-links-single-file.lua *.md -o outfile.html