Make Documenter.jl understand where to search local markdown links

General Usage
1

Hi ! I’m working on my git branch dev for my MyProject.jl project. The README.md is placed at the root of my like any GitHub project it and is referring to a local folder ./tutorial. For example:

See my [tutorial](tutorial) folder.

This tutorial folder contains a README.md. Therefore, in MyProject.jl/docs/make.jl I made a temporary copy before makedocs(:

cp(normpath(@__FILE__, "../../README.md"), normpath(@__FILE__, "../src/home.md"); force=true)
cp(normpath(@__FILE__, "../../tutorial/README.md"), normpath(@__FILE__, "../src/tutorial.md"); force=true)
...
makedocs(...
    pages = Any[
        "Home" => "home.md",
        "Tutorial" => "tutorial.md",

Documenter.jl is generating the online page as xxx.github.io/MyProject.jl/dev/home but the link to my tutorial folder refered by the Home document is incorrectly set: MyProject.jl/dev/home/tutorial (referring to nothing) while Documenter.jl has generated the folder at MyProject.jl/dev/tutorial/index.html. (Note the sidebar is working and referring to valid links).

I did not find documentation concerning this case. What I have to do to fix local links ?

Thanks in advance.

2

I use relative paths. Relative to docs/src. Example: FinEtools.jl/docs/src at main · PetrKryslUCSD/FinEtools.jl · GitHub

3

You can’t really refer to directories, since Documenter doesn’t generate any directory indexes. Instead, in the Markdown source, you should refer to other Markdown files. E.g. given the layout of files you have in docs/src, the link in home.md to the tutorial page should just be [...](tutorial.md).

A link like [...](./tutorial) might sometimes work, but accidentally. That is because when Documenter can’t interpret a link, it just leaves it alone, and it then may or may not match something in the generated HTML.

4

Hi @PetrKryslUCSD in my code I showed, I’m using cp() to copy them in docs/src to make them relative (and I did not show the code removing copied files after makedocs).

Edit: And you, like done in other projects, do not copy the GitHub README.md file but create a new one named index.md. My README.md is a pure markdown file (by pure I mean no Documenter.jl tags) is referring to my other pure markdown files (also relatively) I copied it as index.md (in my code I used the name home.md but I just realized that Documenter.jl does not like not having index.md file). This is sad to have to duplicate files. So I will do search and replace local links in the copied files.

5 
Documenter doesn’t generate any directory indexes

Yes, I should have written: See my [tutorial](tutorial/README.md) folder.

should just be `[...](tutorial.md)`.

Yes, this working, but initially I did not want to do that because markdown files in ./docs/src should be considered as .md.jl files but not as pure .md files since they can have Documenter tags such as @ref @docs and use relative links. My tutorials markdown files do not hold Documenter tags that was my main concern (+ the fact that ./docs/src is too hidden in my taste).

Therefore, you have to choose between having good urls with markdown files (./tutorials) or the having good urls with generated code (./docs/src + [...](tutorial.md)). No escape! So in my make.jl code, after having copied my md files, I have to do some search and replace job such as:

replace "[tutorials](tutorial)" => "[tutorials](tutorial.md)"

and this is working. My ugly code:

infile = normpath(@__FILE__, "../../README.md")
outfile = normpath(@__FILE__, "../src/index.md")
out = open(outfile, "w+")
for line in readlines(infile)
    newline = replace(line, "[tutorials](tutorial)" => "[tutorials](tutorial.md)")
    write(out, newline * "\n")
end
close(out)
6

Ah, yes, Documenter has no concept of files that live outside of docs/src. So if you do copy in some files, you need to handle the links yourself, e.g. by a custom replacement like you suggest. There is an open issue for this:

https://github.com/JuliaDocs/Documenter.jl/issues/551

Just as an FYI, if you’re going down the path of updating the files as you copy them anyway, you can also consider setting the appropriate EditURL value in an @meta block, to make sure the “Edit on GitHub” link points to the actual source file.

1 Like