unresolved internal reference: README.md

[noelwelsh]

Hi! I'm getting the error

 /filename.md

 [1]:  unresolved internal reference: README.md`

in my attempts to use Laika and I don't understand why this is the case.

I have a directory of markdown files and a directory.conf in the same directory. The contents of the directory.conf is

laika.title = "Expressions, Values, and Types"

laika.navigationOrder = [
  intro.md
  expressions.md
]

I don't have a README.md. The documentation says this is optional but I get the above error for all the files in the directory. Adding a README.md makes the error go away, but I don't want to do this for all the content I will eventually port to Laika.

I have tried renaming files, setting titleDocuments configuration, and anything else I can think of, and the problem persists.

I'm using Laika 0.18.2 via sbt in a Scala 3.1.2 project.

The code is at https://github.com/creativescala/creative-scala/tree/laika and the build sbt command will show the error. I'm sure it's a simple config issue but I can't see it! Any help is appreciated.

[jenshalm]

The error comes from using the default Helium theme without a home page. The default template has a top navigation bar with a home icon in the middle. There are two options, depending on what you want to do:

1. You seem to have an index.md. If this is what the icon link should point to, you can simply rename it to README.md. It will be translated to index.html when rendering. This name translation exists to make the setup for Markdown sources more Github-friendly.
2. Alternatively you can overwrite the link in the Helium config as shown in this section: https://planet42.github.io/Laika/0.18/03-preparing-content/03-theme-settings.html#top-navigation-bar

The real problem here is that the error message is so incredibly unhelpful (not pointing to the actual underlying cause at all). I will see if I can find a way to detect this scenario in version 0.19.

[noelwelsh]

Thanks! That's solved the problem for me.

[Ostrzyciel]

(coming from #320)
In my case I had only one file in the input tree: README.rst and I got this exact error. The same error appears when I use multiple source files (README.rst, api.rst). When I use Markdown (with a README.md file) then I don't get this message.

I think my case is a legitimate bug after all...? :)

[jenshalm]

Well, technically I'd still not call it a bug, just bad user experience based on hardcoded defaults. But in general I agree this should be improved, both the error message and the handling of defaults. There are very few rst users for Laika, which is why your specific case never got reported.

Regarding solving your issue with the current version, see option 2. in the accepted answer above.

Regarding improving this, I was thinking about making the default dependent on what the user puts into their input tree. At the moment the theme config inserts a link with either the user-configured target or the hardcoded default into the default template and theme config is only resolved once, before actually running any transformation, so it does not know about your inputs. Then that same theme instance is used against any input trees you use it with. I think the only way to prevent these issues is to insert a dynamic AST element into the tree that resolves at runtime when it can peek into your source tree. I'll think about an approach and then create an issue for improved defaults and ping you both.

[Ostrzyciel]

Ah! Now I understand, thank you :)

I agree that this is counter-intuitive, but in my case it will be easy to fix this using your directions, thanks.