Warning on broken internal links

[smani]

Do we have an option to warn if there are broken internal links in the document?

Example:

# FooBar Details

blah..blah

## Some other section

Refer [FooBar Details](#foobar-detls) section for more information.

The internal link #foobar-detls is misspelt and hence there won't be any hyperlink in the output (or it would be broken). It would be helpful if pandoc can print warnings in these cases.

[neongreen]

Currently Pandoc's document representation has no notion for anchors. Therefore, all links which point to -anchors which were inserted by hand- would be considered “broken”, even though they aren't. Making the warning optional isn't a very good solution, as people who use anchors often would either have to turn it off (and lose the privilege of being warned about broken links, which seems rather useful), or put up with as many warnings as they have anchor links.

Until there is a proper solution (anchors-in-document-model), it might be feasible to simply keep a list of anchors (HTML's <a name=...></a>, LaTeX's \hypertarget, don't know about the rest) found while parsing, and then check internal links against those anchors as well as header identifiers.

[mpickering]

By convention anchors are any identifier (currently id on code blocks, spans, divs and headers). I would like to investigate if this suggestion was possible.

[jgm]

This should be possible, but it's somewhat complex.

We'd need to (a) keep a running list of identifiers used, and (b) have explicit links return "futures" that check this list in state and emit a warning if necessary.

[sebunger]

If it is significantly easier to implement, then implementing this as part of, say, the markdown writer (rather than the reader) would meet my needs at least. I run all documents through markdown to markdown step first anyway auto-fix all the indentations, tables, etc.

I think most other users could also easily add a MD to MD conversion step in order to get the error messages for broken links even if they throw the result of that conversion away.

[tarleb]

I recently used a Lua filter for this purpose. It worked quite well:

local identifiers = {}

function Block (b)
  if b.identifier then
    identifiers[b.identifier] = true
  end
end

function Inline (i)
  if i.identifier then
    identifiers[i.identifier] = true
  end
end

function Link (l)
  local anchor = l.target:match('#(.*)')
  if anchor and not identifiers[anchor] then
    io.stderr:write("broken link: " .. anchor .. "\n")
  end
end

return {
  {Block = Block, Inline = Inline},
  {Link = Link}
}

[jgm]

It would not be that hard to build this into the markdown reader, but it may make more sense to use a filter anyway; after all, it's a check on the AST that makes sense no matter what the input format was.

[sebunger]

Interesting. I'll have a look at AST filters. Thanks for sharing the LUA one!

…

On Wed, 15 Apr 2020 at 10:29, John MacFarlane ***@***.***> wrote: It would not be that hard to build this into the markdown reader, but it may make more sense to use a filter anyway; after all, it's a check on the AST that makes sense no matter what the input format was. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1621 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADGD7CA5LWR7EQWAQEWW6ADRMTPUZANCNFSM4AUDA6WA> .