Link to file with spaces in the name

[dgolda]

I have a file name File with spaces.md
And in another file I'd like to put a link to the first one.
I've tried:

[File with spaces](File with spaces.md)

But I've got:

[error]  [22]: unresolved link id reference: file with spaces
[error] 
[error]   [File with spaces](File with spaces.md)
[error]   ^

So I've tried:

[File with spaces](File%20with%20spaces.md)

But I've got:

[error]   [25]: unresolved internal reference: File%20with%20spaces.md
[error] 
[error]   [File with spaces](File%20with%20spaces.md)

Is it a bug?

BTW I try to use Obsidian.md to edit markdown files and then publish them using Laika.

[jenshalm]

The two formats you have tried are indeed not supposed to work. The spec-compliant way to specify link destinations with spaces is to enclose the target within angle brackets:

[File with spaces](<File with spaces.md>)

However, sadly, this does not work in latest Laika either, and that is indeed a bug. Fortunately it's trivial to fix and this PR (#385) takes care of that. Unfortunately for the latest release I'm not aware of any workaround, so your options boil down to:

• Renaming the files
• Waiting for the 0.19.1 release (which is still 6-8 weeks away)
• Build a local snapshot yourself once the above PR is merged (In a few days)

[dgolda]

I see. Thank you for explanation.
I found spec for link destination: https://spec.commonmark.org/0.30/#link-destination and it says exactly the same.

But unfortunately tool I use (Obsidian.md) doesn't use angle brackets, but encodes spaces in filenames as %20.
Is it possible to add to Laika support for such links as a new feature? Or as an extension (flavor)?

[jenshalm]

Well, strictly speaking Laika does support links with escape sequences, what you need is a very special scenario which is that link validation works even when the link is expressed in a different notation than the actual link destination, which would be an odd corner case where I'm reluctant to support it. It's possible, but unlikely I'd prioritise this before 1.0 is out, which is still many months away.

The only other option you'd have in this case is to disable link validation, which is unfortunate as you have no means to detect dead links then, but at least everything else should work as expected then. The documentation for this configuration can be found here: https://planet42.github.io/Laika/latest/03-preparing-content/02-navigation.html#disabling-validation

[dgolda]

My tests on branch md-link-targets and directory.conf with laika.validateLinks = false

[Filename with spaces](Filename with spaces.md)

laikaSite error:

[error]   [30]: unresolved link id reference: filename with spaces
[error] 
[error]   [Filename with spaces](Filename with spaces.md)
[error]   ^

[Filename with spaces](Filename%20with%20spaces.md)

renders incorrect as:

<a href="Filename%20with%20spaces.md">Filename with spaces</a>

so link doesn't work because filename extension is not .html

[Filename with spaces](<Filename with spaces.md>)

Renders correct as:

<a href="Filename with spaces.html">Filename with spaces</a>

So turning off validation is not a solution for me.

For tests I've made change in laika.ast.RelativePath#parse - from:

        val segments = rest.split("/").toList

to

        val segments = rest.split("/").toList.map(s => java.net.URLDecoder.decode(s, "UTF-8"))

And it works - rendered html is:

<a href="Filename with spaces.html">Filename with spaces</a>

[jenshalm]

Ah, yes. Sorry, I initially thought that 2) would work as I wrongly expected the suffix translation would still happen, but it does not (and for good reasons, so this approach is indeed not viable). I edited my initial response to avoid any confusion.

Solution 3) looks neat, but is not an option either, because RelativePath is an entirely generic implementation of purely logical paths that does not make any assumptions about input or output formats or specific encodings, so this decoding simply does not belong there and while solving your very specific use case, it might lead to bad surprises for others. Just for reference, for those purely logical paths any string is valid. For example, you could have a path consisting of 7 segments which are all the empty string, and it's still valid. Specific encodings or validations should be left to the renderer (in this case the HTML renderer) as the rules for valid references are very different for links in PDF documents for example.

But fortunately I found something that actually works (and this time I tested it). I don't know why I did not think of this right away, but you can easily transform the AST between parsing and rendering yourself if you need adjustments for specific tools.

import laika.ast._

val rules = RewriteRules.forSpans { 
  case ref: LinkPathReference => Replace(ref.copy(path = 
    VirtualPath.parse(java.net.URLDecoder.decode(ref.path.toString, "UTF-8"))
  ))
}

How you register the rule depends on whether you use the sbt plugin or the library API.

For the plugin:

laikaExtensions += laikaRewriteRules(rules)

For the library API:

val transformer = Transformer
  .from(Markdown)
  .to(HTML)
  .usingRules(rules)
  .build

The rewrite rule is applied before the validation phase, so you don't need to disable anything.

This works with Laika 0.19.0, but not with older versions. The concepts behind AST rewriting are documented in this chapter: https://planet42.github.io/Laika/latest/04-customizing-laika/05-ast-rewriting.html

[dgolda]

Thanks a lot! I will check.

[dgolda]

Works for me. Thank you again.