# Basic: Documenter.jl pages open a local folder

**URL:** <https://discourse.julialang.org/t/basic-documenter-jl-pages-open-a-local-folder/125016>\
**Category:** New to Julia\
**Tags:** question, documentation, documenter\
**Created:** [January 21, 2025, 1:02pm UTC](https://discourse.julialang.org/t/basic-documenter-jl-pages-open-a-local-folder/125016 "2025-01-21T13:02:33Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![acroscarrillo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/acroscarrillo/32/214810_2.png) [@acroscarrillo](https://discourse.julialang.org/u/acroscarrillo)\
**Post date:** [January 21, 2025, 1:02pm UTC](https://discourse.julialang.org/t/basic-documenter-jl-pages-open-a-local-folder/125016/1 "2025-01-21T13:02:33Z")

</div>

Hi [its me again!](https://discourse.julialang.org/t/documenter-jl-help-for-first-time-user/124966)

**Context:**  
I have finally a minimal documentation running:

 ![Screenshot 2025-01-21 at 13.47.00](https://global.discourse-cdn.com/julialang/original/3X/c/6/c6e8a1093447300da1ea3c78fe3183da98df953e.png)  
Now I am trying to mimic in `exp.jl` the lovely documentation of [Attractors.jl](https://juliadynamics.github.io/DynamicalSystemsDocs.jl/attractors/stable/), in particular the very nice [Attractors.jl Tutorial](https://juliadynamics.github.io/DynamicalSystemsDocs.jl/attractors/stable/tutorial/#tutorial) as suggested in this [YouTube tutorial](https://www.youtube.com/watch?v=ZDQ28X3mGSo&t=11s).

**Issue:**  
My issue is that if I click here:

 ![Screenshot 2025-01-21 at 13.49.38](https://global.discourse-cdn.com/julialang/original/3X/e/b/ebe076dffaaab5492b1747dc5624736af9bafa73.png)  
My computer opens instead the local folder instead:  
 ![Screenshot 2025-01-21 at 13.52.39](https://global.discourse-cdn.com/julialang/original/3X/7/4/746b5ac93eb930620d2eee11becfe100d2cc99b9.png)

I suspect this has to do with how you reference things which apparently I havent figured it out.

**Full set of details:**  
File structure:

```julia
── Manifest.toml
── Project.toml 
── docs/
│── Manifest.toml
│── make.jl
│── Project.toml 
│── src/
│ │── index.md
│ │── exp.md # automatically generated
│ │── experiments/
│ │ │── exp.jl
── src/
│──Test_Module.jl  
│── test.jl

```

Contents of `docs/src/experiments/exp.jl`:

```julia
# # [exp.jl exp](@id exp)

# ### Test plot

using Plots

plot(rand(100,2))

```

Contents of `docs/make.jl`:

```julia
# docs/make.jl
push!(LOAD_PATH,"../src/")
using Documenter, Test_Module, Literate

# literate the tutorial
Literate.markdown(
    joinpath(@ __DIR__ , "src/experiments/", "exp.jl"), joinpath(@ __DIR__ , "src");
    credit = false
)

makedocs(sitename="My Documentation",
    pages = [
        "index.md",
        "exp.md"
        # "Experiments" => ["experiments/exp_1.md",
                            # "experiments/exp_2.md",
                            # "experiments/exp_3.md",]
    ]
)

```

Contents of `docs/src/index.md`:

```julia
# Test_Module

´´´@contents
´´´

## Documentation

´´´@meta
CurrentModule = Test_Module
´´´

´´´@autodocs
Modules = [Test_Module]
´´´

## Index

´´´@index
´´´

```

**Question: what is going on?**

---

<div class="post-metadata">

**Author:** ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [January 21, 2025, 5:43pm UTC](https://discourse.julialang.org/t/basic-documenter-jl-pages-open-a-local-folder/125016/2 "2025-01-21T17:43:05Z")

</div>

You have to run a local web server to view the documentation [GitHub - JuliaDocs/LiveServer.jl: Simple development server with live-reload capability for Julia.](https://github.com/JuliaDocs/LiveServer.jl) is recommended as a pure-Julia solution, although, if you also have Python, I sometimes find running `python -m http.server` in the `docs/build` folder easier.

Another alternative is to use `prettyurls=false` in the `makedocs` settings. That would allow you to open any of the `.html` files directly in a browser, without a web server. However, most people prefer `prettyurls=true` for when the documentation gets uploaded to, e.g., Github Pages. Some people dynamically switch `prettyurls` between local and remote builds, but this isn’t recommended. See the warning at [Guide · Documenter.jl](https://documenter.juliadocs.org/stable/man/guide/#Building-an-Empty-Document) (scroll down a little bit from that link target):

> You may see setups using
> 
> ```julia
> makedocs(...,
> format = Documenter.HTML(
> prettyurls = get(ENV, "CI", nothing) == "true"
> )
> )
> 
> ```
> 
> The intent behind this is to use `prettyurls=false` when building the documentation locally, for easy browsing, and `prettyurls=true` when deploying the documentation online from GitHub Actions.
> 
> However, this is not recommended. For example, if a `@raw` block references a local image, the correct relative path of that image would depend on the `prettyurls` setting. Consequently, the documentation might build correctly locally and be broken on Github Actions, or vice versa. It is recommended to always use `prettyurls=true` and run a local web server to view the documentation.

The note directly above that warning gives some more details about using a web server:

> By default, Documenter has pretty URLs enabled, which means that `src/foo.md` is turned into `src/foo/index.html`, instead of simply `src/foo.html`, which is the preferred way when creating a set of HTML to be hosted on a web server.
> 
> However, this can be a hindrance when browsing the documentation locally as browsers do not resolve directory URLs like `foo/` to `foo/index.html` for local files. To view the documentation locally, it is recommended that you run a local web server out of the `docs/build` directory. One way to accomplish this is to install the [LiveServer](https://github.com/tlienart/LiveServer.jl) Julia package. You can then start the server with `julia -e 'using LiveServer; serve(dir="docs/build")'`. Alternatively, if you have Python installed, you can start one with `python3 -m http.server --bind localhost`.

---

<div class="post-metadata">

**Author:** ![acroscarrillo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/acroscarrillo/32/214810_2.png) [@acroscarrillo](https://discourse.julialang.org/u/acroscarrillo)\
**Post date:** [January 21, 2025, 9:42pm UTC](https://discourse.julialang.org/t/basic-documenter-jl-pages-open-a-local-folder/125016/3 "2025-01-21T21:42:45Z")

</div>

That was it! Thank you 🙂

For the time being, I am going to use `prettyurls=false` for the time being and will now be studing how to deploy it on GitHub.