Markdown Titles and Prefixed Document Links

Exporting to markdown with some document links to other sections of the project, and using these settings:

This is compiled to this (see the # in the link):

Please see [§2.1](#§2.1 Sun) and [§2.2](#§2.2 Moon) for all the details.

The problem is that an octothorpe # is included in the link. At least for Pandoc this causes the links to fail to resolve as the document title does not actully contain an #:

# §2 Results #

## §2.1 Sun ##

Lørem ipsum dolør sit amet, eu ipsum movet vix...

Test project attached.
CrossReferences.scriv.zip (81 KB)

OK, I think I am wrong here (though links are still broken). There are several ways to create cross-reference links. Scrivener is using internal link formatting which is valid (the octothorpe is the #id anchor in HTML conventions):

pandoc.org/MANUAL.html#internal-linkstext

I was focussed on implicit reference formatting when I was testing this:

pandoc.org/MANUAL.html#extensio … references[text][id]

…where no # is needed.

Anyway the reason the links still break is that Pandoc removes non-letter prefixes when utilising auto-links:

Scrivener produces links like this: [§2.1](#§2.1 Sun), but Pandoc requires the link to be formatted like this: §2.1 or [§2.1][Sun] — the rules for this are listed here: pandoc.org/MANUAL.html#extensio … dentifiers

It would be nice if cross-reference links for Pandoc compiles would follow Pandoc conventions.

Yeah, there are indeed two different kinds of formal internal linking in Pandoc. We ran into this when implementing the hyperlink resolution system to handle duplicate titles. With MMD you can override the ID for a heading, and that gets inserted into the cross-reference array, so you can continue linking to them with [bracket][id] syntax. But the Pandoc method of overriding the ID doesn’t update the internal cross-ref array, and to link to an overridden heading ID, you have to use regular hyperlink syntax, where the octothorpe is a necessary ingredient.

Thus this form of link is valid and necessary at times.

You may note it does use the more common convention if you switch off the feature that converts the link body text to prefix-only. That isn’t to say the direct hyperlink method isn’t an official Pandoc convention either, it is, and again the only way to link to overridden IDs.

But to the point here, if you switch the prefix feature off, you get:

Please see [§2.1 Sun][] and [§2.2 Moon][] for all the details.

I’m not sure why it switches to using direct Hyperlink referencing with that option enabled. It seems to me this would be equally valid, no?

Please see [§2.1][§2.1 Sun] and [§2.2][§2.2 Moon] for all the details.

In my testing that creates a valid HTML file (Pandoc cleans bracketed references using the same algorithm to clean header titles), but I’m trying to figure out if there were any contingencies that would have necessitated changed link methods entirely for this condition. It seems in general we would want to stick with bracket syntax here to benefit from that cleaning algorithm.

Yes, if Scrivener used bracketed links, then prefix-only output works:

For example

Please see [§2.1][§2.1 Sun] and [§2.2][§2.2 Moon] for all the details.

produces this latex:

Please see \protect\hyperlink{sun}{§2.1} and \protect\hyperlink{moon}{§2.2} for all the details.

the prefix is used as the text and the link is consistently cleaned to a functional cross-reference – this link style works for at least HTML (as you confirmed), LaTeX and DOCX outputs without issue.

As you say, MMD allows use of bracketed syntax with custom IDs: fletcher.github.io/MultiMarkdown … ences.html — so [Header ID][] or [Link text][Header ID] get resolved, and can account for custom IDs.

If there is an explicit link ID conflict (i.e. another link with the same name) it would take preference over the implicit bracket destination. Pandoc allows one to set explicit header IDs using {#ID} at the end of the heading text for such cases: github.com/jgm/pandoc/issues/6085

Yeah, it would be nice to see that added at some point. MMD has an odd corner like that as well, between how figures are referenced, and the rest of the system: they are the only ID element you can’t bracket link, so you must use a similar direct hyperlink method. So you can [Reference A Table] like so, but a figure like this.

At any rate, this all explains why the code is there in Scrivener, to make direct hyperlinks to binder items with identical titles, but not why it is being made use of in this particular context. Unless I’m missing something, I suspect this will be an easy fix.

Thanks for the feedback Ioa!