Document Links ⇨ Markdown: Problems with Suffixes in [Link Targets]

[nontroppo]

Several markdown engines or extensions allow one to add properties to Headings, for example:

# My heading # {#foo .unnumbered}

One way to do this is with the Title Suffixes options in the Compiler. I can add some custom metadata to a document:

Then in the Title Suffix I add this to the suffix:

This now generates well-formed Markdown (using the option to place suffix after hashes):

# Mercury # {#mercury .left}

So far so good, however let’s say i have a Scrivener [Document link] to this document/heading. I disable the compiler options to modify document links just in case:

But the compiled markdown with the document link shows this:

# Mars # { }

Now what are the possibilities of warp drive  ([see Mercury][Mercury # {#mercury .left}])? Cmdr Riker's nervous system has been invaded by an unknown microorganism. The organisms fuse to the nerve, intertwining at the molecular level.

The link text is fine, but the [link target] has # {#mercury .left} suffix data appended to the target text (this will break the link; the link should be [see Mercury][Mercury]).

@AmberV — I’ve read through §24.8 of the user manual, but it isn’t clear what should happen in the case of markdown link resolution. To make a working link there should be no suffix data in the [link target]. I’ve tried this option set too just in case but the result is the same:

Sample project here:

SuffixIssue.scriv.zip (75.2 KB)

p.s. I realise injecting an ID may cause other problems if header text and ID conflict, but that is a separate problem concerning markdown itself.

[AmberV]

This is a bit of a tricky one. You’re looking at these settings through the lens of this specific implementation producing an undesirable result, but what you are observing here isn’t a bug, and is in fact generally a desirable result. Additionally the settings in this panel have nothing to do with addressing, they specifically apply to whether “Name of Section”, if hyperlinked to a binder item of that name, should be modified with any changes to the heading via Section Layouts.

The heading text is being modified by the layout, so what was typed into the binder is no longer the de facto heading, for purposes of cross-referencing. To remove your very specific approach here and use a different example, let’s say we’re adding <$n>) to the heading, and compiling with default “Basic Pandoc” settings:

# 1) Tested Heading

## Subsection

A link to [1) Tested Heading][]

In this case the prefix and suffix are added to the visible text of the hyperlink, which in this case also matches the actual heading, and thus its address, so we can use the simple implicit link form.

If we go into Document Title Links and disable that feature entirely, the intent of this feature here is to modify the visible text, or in this case only printing the section heading and not its numbering:

# 1) Tested Heading

## Subsection

A link to [Tested Heading][1) Tested Heading]

Now we must use the referenced internal link format, since the physical heading differs from the visible text. The address part of that, in the second set of brackets, must match the physical heading in order to be valid. It cannot be [Tested Heading][], or [see Tested Heading][Tested Heading], because that heading doesn’t exist.

Now, all of that said, I can see an argument where if the Place prefix|suffix inside hashes checkbox is disabled, then we can very safely presume that whatever is in the fields is not part of the physical heading, and should only be included in the visible part of a hyperlink if applicable, but never the address part. Granted someone could be using these settings very creatively to end up with a result that still does have the actual heading “outside” of the original title area, but I’d say what you’re trying to do is a lot more common than anything tortured like putting two headings into one layout or something of that nature.

So overall I think that’s a safe assumption (regardless of the Document Title Links settings) whereas the overall assumption that the prefix and suffix should never be part of address isn’t safe. Again those settings are for adjusting the visible link when the hyperlink matches the binder item title, and that’s it.

[nontroppo]

OK, I think I understand the general logic here.

In my example the closing # itself is also added to the [link target] (i.e. the first # here is not in my suffix data but comes from Scrivener injecting hashes: # {#mercury .left}), I assume the closing hash being added to the target is not right under any circumstances?

if the Place prefix|suffix inside hashes checkbox is disabled, then we can very safely presume that whatever is in the fields is not part of the physical heading

Yes, I’d agree with this and if the compiler could make that assumption then this particular problem would be solved. Could this be done?

[AmberV]

Ah, yeah that’s a good point. The hash shouldn’t ever be included as part of the address. That part can be worked around by switching closing hashes off with the gear button at the top of Section Layouts.

Yes, I’d agree with this and if the compiler could make that assumption then this particular problem would be solved. Could this be done?

I couldn’t speak to how difficult it would be change that, but I’ve put it on the list at any rate.