Caution against dynamic prettyurls

We should steer people away from using

    prettyurls = get(ENV, "CI", nothing) == "true"

(or even `prettyurls = false`) and towards using `LiveServer`.

It is best to have a consistent setting and to always use a webserver
when viewing documentation locally. This avoids situations where there
might be subtle difference with `prettyurls=true` or `prettyurls=false`
and the documentation might work correctly when viewed locally, but be
subtly broken (without an error message!) when deploying on GitHub
Action. One such situation is a `@raw` block that references a local
image. The correct relative path of that image would be different
depending on the `prettyurls` setting.

docs/src/man/guide.md

@@ -147,19 +147,18 @@ build/
        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`
-       (or `python -m SimpleHTTPServer` with Python 2).
+       installed, you can start one with `python3 -m http.server --bind localhost`.
 
-    2. You can disable the pretty URLs feature by passing `prettyurls = false` with the
-       [`Documenter.HTML`](@ref) plugin:
+    2. You can disable the pretty URLs feature by passing `prettyurls = false` with
+       [`Documenter.HTML`](@ref):
 
        ```julia
        makedocs(..., format = Documenter.HTML(prettyurls = false))
        ```
 
-       Alternatively, if your goal is to eventually set up automatic documentation deployment
-       with e.g. Travis CI or GitHub Actions (see [Hosting Documentation](@ref)), you can also use their environment
-       variables to determine Documenter's behavior in `make.jl` on the fly:
+       For simple projects, it may be suitable to set `prettyurls` on the fly depending on
+       whether the documentation is being built locally or, e.g., in a Github Action (see
+       [Hosting Documentation](@ref)):
 
        ```julia
        makedocs(...,
@@ -169,6 +168,18 @@ build/
        )
        ```
 
+       This relies on the environment variable `CI` that is set when running on GitHub Actions,
+       and offers the benefit of making the documentation easy to view locally while still
+       deploying with the recommended URL scheme. However, be aware there can be subtle
+       differences between `prettyurls=true` and `prettyurls=false`. For example, if a
+       [`@raw` block](@ref @raw-format-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. Thus, the *recommended* approach is to maintain a consistent setting and to
+       always use LiveServer or `python3 -m http.server` to view the locally built
+       documentation.
+
+
 !!! warning
 
     **Never** `git commit` the contents of `build` (or any other content generated by

src/html/HTMLWriter.jl

@@ -279,20 +279,17 @@ Sets the behavior of [`HTMLWriter`](@ref).
 
 **`prettyurls`** (default `true`) -- allows toggling the pretty URLs feature.
 
-By default (i.e. when `prettyurls` is set to `true`), Documenter creates a directory
-structure that hides the `.html` suffixes from the URLs (e.g. by default `src/foo.md`
-becomes `src/foo/index.html`, but can be accessed with via `src/foo/` in the browser). This
-structure is preferred when publishing the generate HTML files as a website (e.g. on GitHub
-Pages), which is Documenter's primary use case.
+By default (i.e., when `prettyurls` is set to `true`), Documenter creates a directory
+structure that hides the `.html` suffixes from the URLs (e.g., by default `src/foo.md`
+becomes `src/foo/index.html`, but can be accessed via `src/foo/` in the browser). This
+structure is preferred when publishing the generated HTML files as a website (e.g., on
+GitHub Pages), which is Documenter's primary use case. However, when building locally
+viewing the resulting pages requires a running webserver. It is recommended to use the
+[`LiveServer` package](https://github.com/tlienart/LiveServer.jl) for this.
 
 If `prettyurls = false`, then Documenter generates `src/foo.html` instead, suitable for
-local documentation builds, as browsers do not normally resolve `foo/` to `foo/index.html`
-for local files.
-
-To have pretty URLs disabled in local builds, but still have them enabled for the automatic
-CI deployment builds, you can set `prettyurls = get(ENV, "CI", nothing) == "true"` (the
-specific environment variable you will need to check may depend on the CI system you are
-using, but this will work on Travis CI).
+locally viewing the documentation without `LiveServer`, as browsers do not normally
+resolve `foo/` to `foo/index.html` for local files.
 
 **`disable_git`** can be used to disable calls to `git` when the document is not
 in a Git-controlled repository. Without setting this to `true`, Documenter will throw