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
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)
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.
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
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.
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
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.
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 (
[...](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")
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:
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.