Export text links: differences between standard HTML and Markdown

[brookter (David Bertenshaw)]

Hi,

This is probably my being confused again, but …

As far as I can tell, the export command treats text links to other notes differently when markdown is being used, compared to when the ‘basic’ HTML export is in operation.

Take a simple case. Two notes inside two separate containers. The note Source has two types of link to the note Target:

• a text link (via the standard mechanism)
• an explicit export action link linkTo(Target).

The test is to export the file, twice. Firstly with the standard HTML no-markdown export, which gives this result:

As you can see, both links are identical, as expected:

<a href="../Container_B/Target.html">Target</a> (Text link)

They evaluate to the correct file path of Target and so are viable links in Safari:

file:///Users/david/Documents/Tinderbox%20exports/Testlinks%20(markdown)/Target.html

But when markdown is in operation, we get this:

I.e. the text link has an additional / at the front of the path

<a href="/../Container_B/Target.html">Target</a> (Text link)

which gives the dead link:

file:///Target.html

Is this expected behaviour? Is there a setting to remove the / from the front of the path, or am I missing something obvious?

(BTW, I get the same behaviour with CommonMark, Pandoc, and MultiMarkdown, if that’s relevant.)

Many thanks.

[satikusala (Michael Becker)]

I just tested all the scenarios and you’re right. It appears that the traditional link (e.g. with parking lot mechanisms) in markdown is add in a leading “/”.

I think this is something for @eastgate to look in to.

TBX L - linkTo Export Code.tbx (92.5 KB)

[eastgate]

Try using ^root^ to get the relative path to the root of the server.

[brookter (David Bertenshaw)]

Thanks for testing, Michael!

[brookter (David Bertenshaw)]

Hi, Mark.

Thanks for the response!

I’ve read the ^root^ entry on atbref and it seems to be about pointing specific elements to a location within the file, rather than a general setting to ensure that any link converted from markdown doesn’t begin with a leading /.

How would I use ^root^ to remove that initial ‘/’?

[UPDATE]

After a bit of ferreting around in the actual atbref.tbx file, I tried ^setRoot(/Users/david/Documents/Testlinks/)^ in the template. I get the following:

As you can see, the text link still has an additional /, and the link doesn’t work. The linkTo version does work, and so do both types of links with the non-markdown version:

It does look like the issue is the automatic conversion of text links from markdown.

Is there something else I should be trying?

Many thanks,

David

[mwra (Mark Anderson)]

@brookter

atbref and it seems to be about pointing specific elements to a location within the file,

Where does it say that? My ^root^ description states:

Returns the relative path from the current file to the directory that contains the cover page. When concatenating ^root^ with a path, it is not necessary to add a trailing (folder) slash as this is created as part of the ^root^ output. Thus

I suspect you’ve misunderstood the term “the current file”. The page is talking about export code so the task is about getting the relative path from the HTML file (as exported from the note using a template using this code) to the root of the exported site.

Still, my original note dates from 2008 (and likely earlier0 when the was little action code and the code was more focussed on true export and internal preview wasn’t yet talked about.

I’ve just updated my article of ^root^ and I hope it makes things a bit clearer. If not, please explain how you think the feature should be explained. I’ve also added cross-link to ^setRoot()^ for finer control.

[brookter (David Bertenshaw)]

Hi Mark,

I was trying to understand Mark B’s helpful suggestion to use ^root^ to remove the false leading / which is produced when exported text links with markdown (see the rest of the thread for details).

The atbref article (and the couple of other references I’ve found) seem to use it to provide a special path for a specific item:

^root^images/icon.gif

which seems clear enough. You’re right that I meant ‘in the file system’ rather than ‘in the file’, but it’s still changing a specific path for a specified element.

But that’s not what I need to do — I need to stop all automatically generated text links in a markdown → html export from being broken because they put an extra / at the front (i.e. they produce href="/.." instead of href="..").

I thought setRoot might sort the problem out, but it doesn’t: it merely produces the invalid href="//Users" instead of the expected valid href="/Users".

I can’t see a way to make either of these work for every automatically generated text link. Of course, I could just use linkTo, which does work with Markdown, but I was hoping to avoid that!

Bear in mind the automatic text link generation does work perfectly well for normal html export – it’s only when the underlying prototype is markdown that the problem occurs. This is why I think it may be to do with the markdown conversion, and why a root/setRoot solution may not be working.

But, of course, my knowledge of these things is limited, so if there is a way to use root or setRoot, or anything else …, to solve the problem, I’d be very grateful! At the moment, my solution is to do a post-export search and replace in BBEdit, removing the annoying leading /s, but I’m hoping there’s an in-tinderbox solution…

In case it helps, here’s the test file the screenshots are from:

Testlinks.tbx (116.4 KB)

(Just toggle the prototypes of Source and Target to and from Markdown to see how the resulting links are altered in their Export panels.)

Many thanks…

[mwra (Mark Anderson)]

@brookter

This is why I think it may be to do with the markdown conversion, and why a root/setRoot solution may not be working.

Avoiding the pejorative ‘bug’, it _appears_to be a failure within the Markdown preview script, seeing that normal HTML export works.

Given that context, it might ge worth investigating in a Markdown forum for issue relating to parsing URLs, bearing in mind the Markdown is parsing the ‘HTML’ output of Tinderbox export (even in a ‘preview’ context). IOW, something in Markdown parsing is adding a / to the Tinderbox output.

Put another way, the Markdown script post-processes the HTML export output stream. Markdown prototype HTML-related attribute customisations simply suppresses things like inserting <p> paragraph tags. They don’t touch anything related to generating link mark-up. The non-Markdown result shows you what is otherwise going as input to the Markdown script. Odd.

[satikusala (Michael Becker)]

@mwra

appears_to be a failure within the Markdown preview script

Actually, in my test it was the internal TBX link that was causing the issue, I think. Let’s jump on a zoom and I’ll show you. Also, there is something else I need to cover with you.

[mwra (Mark Anderson)]

@brookter

In case it helps, here’s the test file the screenshots are from:

Testlinks.tbx (116.4 KB)

Aha. I duplicated the Markdown prototype and deleted the $HTMLPreviewCommand value. IOW, it is the same customisation except that no post-processing happens. Now we see this for the links:

<h2>Source2</h2>
## Test links
Link to: [Target](/Container_B/Target.html)  (Text link)

Link to: <a href="Container_B/Target.html">Target</a> (linkTo) 

In the first case the initial slash is still there, which we know (from the ‘normal’ HTML version) is not wanted. I think Tinderbox may be at fault here as the code [Target](/Container_B/x/Target.html) is being generated by Tinderbox. This is an aspect of which I was not aware. IOW, with the Markdown prototype set, Tinderbox silently (and hitherto undocumented) exports not an HTML link for text notes but custom Markdown link Mark-up. In doing so it fails to omit the opening slash causing downstream failure. Given that the app does omit said slash for normal HTML link generation, the retention of the slash seems egregious but I’m not expert enough in Markdown (and its many differing/clashing flavours) to know what is right here.

@eastgate, is the extra opening path slash needed for some other purpose?

What puzzles me is why this is the first report of this issue, which Ive been able to replicate based on @brookter’s descriptions. I see the same reported behaviour in v9.1.0 and in more recent (beta) builds. however, I wonder if v9.1.0 differs in the above respect from earlier release versions.

[brookter (David Bertenshaw)]

Hi Mark,

[Deleted the original to make it clear who I was replying to…]

I’m getting a little lost in the technicalities of what’s going on behind the scenes here, so I’m glad you’re making sense of it!

I don’t know whether the issue is recent or not: this is the first time (in 10 years…) I’ve tried to export as a web site, so much of it is new to me and I wasn’t sure whether I was doing something wrong.

@eastgate: Mark, I’ve put everything I know about the problem in this thread, including the test file. Do you need a separate Issue report by Email, or will this do?

Thanks!

[mwra (Mark Anderson)]

No problem, the source of the issue isn’t obvious and it took some head-scratching to flush out the causal disconnect. Having just explored this further (off-forum) with @satikusala, I should clarify one further point for worried Markdown users…

The above problem affects only Tinderbox text links, IOW, blue links in $Text that are links to other Tinderbox notes. If you construct you’re own links using explicit Markdown mark-up you should be fine (which explains why Michael, who does the latter, is having no exported link breakage)

<h2>Source2</h2>
## Test links
Link to: [Target](/Container_B/Target.html)  (Text link)

(Manual edit of above source)
Link to: [Target](Container_B/Target.html)  (Text link) <!-- note opening '/' of path removed-->

Link to: <a href="Container_B/Target.html">Target</a> (linkTo) 

Passing the above to Markdown should result in the broken first link but the other two work. Of course if you’ve 100s of internal links to export and are using Tinderbox text links at present, this is an un welcome hiccup as you need to either re-write all the text notes as explicit mark-up or wait fro an app fix, the latter assuming my diagnosis is correct.

One other workaround, if needing to export a lot of text links. Make a copy of the existing ‘Markdown’ template (e.g. as ’ Markdown1’). Change the copy’s $HTMLPreviewCommand value to nothing (i.e. delete the existing value), and change the $HTMLExportExtension from “.html” to “.md”. The result is that you will export ‘raw’ Markdown files which you can then fix before processing with Markdown to get the HTML. This is a temporary workaround, so it is obviously extra work, but I note this in case there is someone who’s hit this on a deadline!

What if you want to hand code those links in Markdown? See next post:

[mwra (Mark Anderson)]

Example file below but cor part if to achieve the following. the first is the ‘bad’ expisting Tinderbox mmd text link output. the second is coded ‘manually’ in Markdown but so as you give output like the working HTML export:

The note text creating the above. Note the coding os the second link in the page:

In the doc below, there are 3 versions of the source container A, each with the same ‘source’ note linking to note Target. “Container A” is set for normal HTML export. “Container A2” is set to use the Tinderbox default ‘Markdown’ prototype, thus generating the broken first link. “Container A3” uses a copy of the default ‘Markdown’ prototype but with the $HTMLPreviewCommand value deleted.

I’ve simplified the HTML template in the original example to cut out code that may obscure things and listed the link descriptions in ‘source’ separate from the 3 actual links so it is easier to compare the 3 forms of links.

If you want to export from this file, first use the Export Inspector to set the export location. Otherwise, compare the ‘Source’, ‘Source1’ and ‘Source2’ notes in text, preview and (most informatively) export tabs.

Document: Testlinks-ed.tbx (143.6 KB)

[brookter (David Bertenshaw)]

That’s excellent, Mark – thanks for filling in the gaps and fleshing out the issue!

Cheers

David.