# Documenter.jl: Linking to specific files and Documentation of Scripts

**URL:** <https://discourse.julialang.org/t/documenter-jl-linking-to-specific-files-and-documentation-of-scripts/23847>\
**Category:** General Usage\
**Tags:** documenter, literate-programming\
**Created:** [May 4, 2019, 1:37pm UTC](https://discourse.julialang.org/t/documenter-jl-linking-to-specific-files-and-documentation-of-scripts/23847 "2019-05-04T13:37:39Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [May 4, 2019, 1:37pm UTC](https://discourse.julialang.org/t/documenter-jl-linking-to-specific-files-and-documentation-of-scripts/23847/1 "2019-05-04T13:37:39Z")

</div>

I am currently writing a package and want to document everything from the beginning on. [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) is great for that.

I am currently writing and example script that also reproduces a previous result (from code in Matlab) but now in Julia. So I would like to have that as a standalone Script (standalone in the sense that: Having installed the Package I am working on it can just run without prior stuff).

I cam to two points, where I wondered: How do I do that in Julia (or Documenter)?

1. Is there a possibility to provide a short description for a script file, like one does with the doc strings for functions? My idea is to provide the title and the main purpose of the script and maybe a reference where to get further informations

2. I am accompanying the script by a illustrative page in the documentation and would like to link to the current (or maybe for older documentations even old versions) of a file in the repository. How can that be done in Documenter markdown?

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [May 4, 2019, 1:59pm UTC](https://discourse.julialang.org/t/documenter-jl-linking-to-specific-files-and-documentation-of-scripts/23847/2 "2019-05-04T13:59:59Z")

</div>

Sounds like you might find [Literate.jl](https://github.com/fredrikekre/Literate.jl) ([ANN: Literate.jl](https://discourse.julialang.org/t/ann-literate-jl/10651)) useful (disclaimer: I am the author of that package). Your usecase sounds just like the one I had for writing the package in the first place.

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [May 4, 2019, 2:26pm UTC](https://discourse.julialang.org/t/documenter-jl-linking-to-specific-files-and-documentation-of-scripts/23847/3 "2019-05-04T14:26:47Z")

</div>

That is definitely a very nice way to pursue exactly my purpose.

Is the `@REPO_ROOT_URL`maybe also directly available in Documenter or is that a feature of your package? The one reason I am asking is, that one of my result images I have in the documentation takes 10 hours to compute so it would be better to have that just in the documentation as a result and not computed (for example using an `@example` block in Documenter.

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [May 6, 2019, 8:40am UTC](https://discourse.julialang.org/t/documenter-jl-linking-to-specific-files-and-documentation-of-scripts/23847/4 "2019-05-06T08:40:15Z")

</div>

Today I tried to get the package running and I am already quite satisified – I added the following lines to the `make.jl´

```julia
tutorialsInputPath = joinpath(@ __DIR__ , "..", "src/tutorials")
tutorialsRelativePath = "tutorials/generated"
tutorialsOutputPath = joinpath(@ __DIR__ ,"src/"*tutorialsRelativePath)
tutorials = ["TutorialA,TutotialB"]
menuEntries = ["Menu Entry for Tutorial A", "Menu Entry for Tutorial B"]
TutorialMenu = Array{Pair{String,String},1}()
for (i,tutorial) in enumerate(tutorials)
    global TutorialMenu
    sourceFile = joinpath(tutorialsInputPath,tutorial*".jl")
    targetFile = joinpath(tutorialsOutputPath,tutorial*"md")
    Literate.markdown(sourceFile,tutorialsOutputPath; name=tutorial, credit=false)
    push!(TutorialMenu, menuEntries[i] => joinpath(tutorialsRelativePath,tutorial*".md") )
end

```

which enables to just add the line

```julia
        "Tutorials" => TutorialMenu,

```

to the menu of Documenter. That works great, though it would be nice to also have a check whether the example needs to be generated. Further, the meta link top left (which work locally in Documenter) won’t work when I compile the docs on my machine.

And I am not sure whether I encountered a bug but the lines

```julia
#md[`functionA`](@ref)s
#nb functionA
#. For a
#md[typeB](@ref)

```

I wanted to use to refer to functions and types in the documentation. However that gets translated in to a code block with

```julia
@example TutorialA
#md[`functionA`](@ref)s
#. For a
#md[typeB](@ref)

```

as content. I con’t understand why.  
**Edit** : Now I _do_ understand 😉 The `#md` just filters out but the following part of the line is still handled as `Julia` code, so pure markdown just used in markdown has to be prepended `#md #`.

The final thing I have to figure out is the `jl` format: Since all markdown and notebook “stuff” is commented, It should directly also run as a Julia script right? So the Julia processing would just remove a little bit of comments to make the src code file more readable?