Basic: Documenter.jl pages open a local folder

New to Julia
, ,
2

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. 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 (scroll down a little bit from that link target):

You may see setups using

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

4 Likes