# Make Documenter.jl understand where to search local markdown links

**URL:** <https://discourse.julialang.org/t/make-documenter-jl-understand-where-to-search-local-markdown-links/84012>\
**Category:** General Usage\
**Tags:** documenter\
**Created:** [July 10, 2022, 9:13am UTC](https://discourse.julialang.org/t/make-documenter-jl-understand-where-to-search-local-markdown-links/84012 "2022-07-10T09:13:07Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![Lecrapouille](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lecrapouille/32/24071_2.png) [@Lecrapouille](https://discourse.julialang.org/u/Lecrapouille)\
**Post date:** [July 10, 2022, 9:13am UTC](https://discourse.julialang.org/t/make-documenter-jl-understand-where-to-search-local-markdown-links/84012/1 "2022-07-10T09:13:07Z")

</div>

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:

```julia
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(`:

```julia
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.

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [July 10, 2022, 2:17pm UTC](https://discourse.julialang.org/t/make-documenter-jl-understand-where-to-search-local-markdown-links/84012/2 "2022-07-10T14:17:30Z")

</div>

I use relative paths. Relative to `docs/src`. Example: [FinEtools.jl/docs/src at main · PetrKryslUCSD/FinEtools.jl · GitHub](https://github.com/PetrKryslUCSD/FinEtools.jl/tree/main/docs/src)

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [July 11, 2022, 6:56am UTC](https://discourse.julialang.org/t/make-documenter-jl-understand-where-to-search-local-markdown-links/84012/3 "2022-07-11T06:56:13Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Lecrapouille](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lecrapouille/32/24071_2.png) [@Lecrapouille](https://discourse.julialang.org/u/Lecrapouille)\
**Post date:** [July 11, 2022, 8:33pm UTC](https://discourse.julialang.org/t/make-documenter-jl-understand-where-to-search-local-markdown-links/84012/4 "2022-07-11T20:33:49Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Lecrapouille](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lecrapouille/32/24071_2.png) [@Lecrapouille](https://discourse.julialang.org/u/Lecrapouille)\
**Post date:** [July 11, 2022, 9:12pm UTC](https://discourse.julialang.org/t/make-documenter-jl-understand-where-to-search-local-markdown-links/84012/5 "2022-07-11T21:12:15Z")

</div>

```julia
Documenter doesn’t generate any directory indexes

```

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

```julia
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:

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

```

and this is working. My ugly code:

```julia
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)

```

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [July 12, 2022, 6:33am UTC](https://discourse.julialang.org/t/make-documenter-jl-understand-where-to-search-local-markdown-links/84012/6 "2022-07-12T06:33:43Z")

</div>

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](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](https://juliadocs.github.io/Documenter.jl/stable/man/syntax/#@meta-block), to make sure the “Edit on GitHub” link points to the actual source file.