# ANN: Documenter 0.27

**URL:** <https://discourse.julialang.org/t/ann-documenter-0-27/62726>\
**Category:** Package Announcements\
**Tags:** package, announcement, documenter\
**Created:** [June 11, 2021, 9:51am UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726 "2021-06-11T09:51:41Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![pfitzseb](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/pfitzseb/32/45566_2.png) [@pfitzseb](https://discourse.julialang.org/u/pfitzseb)\
**Post date:** [June 11, 2021, 9:51am UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/1 "2021-06-11T09:51:41Z")

</div>

Hey everyone,

version 0.27 of [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) just got released. It brings a bunch of [bug fixes and general improvements](https://github.com/JuliaDocs/Documenter.jl/releases/tag/v0.27.0), but also a new feature:

### Warnings and SEO for outdated docs

Documenter now injects a tiny piece of JavaScript into its HTML output, which checks whether there is a newer version of the documentation available. If so, we display a prominent warning and add a `meta` tag that stops search engines from indexing the page.

Adding this warning to existing docs is a manual process, but should be as easy as calling

```julia-auto
using DocumenterTools
OutdatedWarning.generate("/path/to/your/docs")

```

on e.g. the `gh-pages` branch in your package’s repository. Note that you’ll need to figure out which of these changes to check in; I’d suggest running it on the entirety of the docs just before tagging a new version (which has docs built with the Documenter 0.27).

Check out old versions of the [Julia docs](https://docs.julialang.org/en/v1.2/) if you want to see this feature in action!

If you’re a package author, we urge you to upgrade to Documenter 0.27 as soon as possible and maybe even run the `OutdatedWarning.generate` process on your docs to (hopefully) reduce user confusion and keep search results more relevant.

As always, please file bug reports and feature requests on [GitHub](https://github.com/JuliaDocs/Documenter.jl/issues/new). Usage questions are welcome on Discourse and in the `#documentation` channel on the Julia Slack.

---

<div class="post-metadata">

**Author:** ![jgreener64](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jgreener64/32/2483_2.png) [@jgreener64](https://discourse.julialang.org/u/jgreener64)\
**Post date:** [June 11, 2021, 10:55am UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/2 "2021-06-11T10:55:12Z")

</div>

This single feature will have a large effect on reducing a common pain point for new users. Thanks a lot!

---

<div class="post-metadata">

**Author:** ![EvoArt](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/evoart/32/25357_2.png) [@EvoArt](https://discourse.julialang.org/u/EvoArt)\
**Post date:** [June 11, 2021, 5:02pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/3 "2021-06-11T17:02:31Z")

</div>

Completely agree. This great!

---

<div class="post-metadata">

**Author:** ![ctkelley](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ctkelley/32/10684_2.png) [@ctkelley](https://discourse.julialang.org/u/ctkelley)\
**Post date:** [June 11, 2021, 10:55pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/4 "2021-06-11T22:55:43Z")

</div>

How do I convince github actions to use .27. I tried putting

```julia
[compat]
Documenter = "0.27"

```

in docs/Project.toml

and the run failed with

```julia
Run julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
4
Path `/home/runner/work/SIAMFANLEquations.jl/SIAMFANLEquations.jl` exists and looks like the correct package. Using existing path.
5
   Resolving package versions...
6
  Installing known registries into `~/.julia`
7
       Added registry `General` to `~/.julia/registries/General`
8
ERROR: Unsatisfiable requirements detected for package DocumenterLaTeX [cd674d7a]:
9
 DocumenterLaTeX [cd674d7a] log:
10
 ├─possible versions are: 0.1.0-0.2.0 or uninstalled
11
 ├─restricted to versions * by an explicit requirement, leaving only versions 0.1.0-0.2.0
12
 └─restricted by compatibility requirements with Documenter [e30172f5] to versions: uninstalled — no versions left
13
   └─Documenter [e30172f5] log:
14
     ├─possible versions are: 0.19.0-0.27.0 or uninstalled
15
     └─restricted to versions 0.27 by an explicit requirement, leaving only versions 0.27.0

```

When I leave this out of docs/Project.toml I wind up with version .25.2

---

<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:** [June 11, 2021, 11:51pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/5 "2021-06-11T23:51:46Z")

</div>

DocumenterLaTeX is a [paused](https://github.com/JuliaDocs/Documenter.jl/pull/1493) experiment and you shouldn’t need it with Documenter \>= 0.26. Try to remove that first.

---

<div class="post-metadata">

**Author:** ![juliohm](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/juliohm/32/215266_2.png) [@juliohm](https://discourse.julialang.org/u/juliohm)\
**Post date:** [June 12, 2021, 11:43am UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/6 "2021-06-12T11:43:04Z")

</div>

Is there a section of the Documenter.jl documentation explaining the feature? I couldn’t find it, and was wondering what exactly is the path to the documentation. You mention “gh-pages” so this is the branch on github where the documentation is committed?

---

<div class="post-metadata">

**Author:** ![aplavin](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/aplavin/32/222056_2.png) [@aplavin](https://discourse.julialang.org/u/aplavin)\
**Post date:** [June 12, 2021, 11:57am UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/7 "2021-06-12T11:57:14Z")

</div>

Is it possible to add a distinction between “old version of documentation” vs “documentation is up-to-date, but for an old package version”? These two may imply very different things from a user’s POV: docs are old =\> always go to the updated ones; docs are for an old version =\> stay there if this is the version you need.  
For example, julia 1.0-1.5 docs would show the “old docs” message, while julia 0.x “docs fine, but old version”.

---

<div class="post-metadata">

**Author:** ![ctkelley](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ctkelley/32/10684_2.png) [@ctkelley](https://discourse.julialang.org/u/ctkelley)\
**Post date:** [June 12, 2021, 12:27pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/8 "2021-06-12T12:27:37Z")

</div>

That did it. I clearly missed the memo on DocumenterLaTeX.  
Thanks.

---

<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:** [June 12, 2021, 1:24pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/9 "2021-06-12T13:24:32Z")

</div>

> [@juliohm](#):
>
> Is there a section of the Documenter.jl documentation explaining the feature?

[`OutdatedWarning.generate`](https://juliadocs.github.io/Documenter.jl/dev/lib/public/#DocumenterTools.OutdatedWarning.generate)

> [@juliohm](#):
>
> You mention “gh-pages” so this is the branch on github where the documentation is committed?

Yea, you give the path to the folder where you have checked out the `gh-pages` branch.

> [@aplavin](#):
>
> Is it possible to add a distinction between “old version of documentation” vs “documentation is up-to-date, but for an old package version”? These two may imply very different things from a user’s POV: docs are old =\> always go to the updated ones; docs are for an old version =\> stay there if this is the version you need.  
> For example, julia 1.0-1.5 docs would show the “old docs” message, while julia 0.x “docs fine, but old version”.

For Julia 1.X there is just one document. So even though there is docs for 1.0.5 specifically you should always read the latest one (hence why the default url is just `/v1` and not `v1.6` for example).

---

<div class="post-metadata">

**Author:** ![aplavin](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/aplavin/32/222056_2.png) [@aplavin](https://discourse.julialang.org/u/aplavin)\
**Post date:** [June 12, 2021, 2:14pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/10 "2021-06-12T14:14:43Z")

</div>

> [@fredrikekre](#):
>
> For Julia 1.X there is just one document. So even though there is docs for 1.0.5 specifically you should always read the latest one (hence why the default url is just `/v1` and not `v1.6` for example).

Julia itself was just an example, the general point still stands.  
If `MyPackage` latest version is 0.5.5, then docs for 0.5.1-0.5.4 should show “old docs” label, while 0.1-0.4 should show “old package version” label. These two meanings are different for those who use e.g. the 0.3 version and doesn’t want to upgrade.

---

<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:** [June 12, 2021, 4:05pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/11 "2021-06-12T16:05:05Z")

</div>

I was suggesting you should do the same. Do you really want user to use and for you to support multiple breaking releases? If you indeed are reading the correct documentation then you can just ignore the warning.

Would a wording like

> This documentation is not for the latest version.

be better and be applicable in both cases?

---

<div class="post-metadata">

**Author:** ![juliohm](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/juliohm/32/215266_2.png) [@juliohm](https://discourse.julialang.org/u/juliohm)\
**Post date:** [June 12, 2021, 4:08pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/12 "2021-06-12T16:08:31Z")

</div>

Thank you @fredrikekre . Do you have an example package with the warning enabled in the docs/make.jl file?

---

<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:** [June 12, 2021, 4:10pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/13 "2021-06-12T16:10:55Z")

</div>

It is enabled by default for _new_ documentation generated using Documenter \>= 0.27. The `DocumenterTools.OutdatedWarning.generate` function I linked to above is for adding the warning to _old_ versions that have already been built with Documenter \< 0.27.

---

<div class="post-metadata">

**Author:** ![aplavin](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/aplavin/32/222056_2.png) [@aplavin](https://discourse.julialang.org/u/aplavin)\
**Post date:** [June 12, 2021, 4:41pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/14 "2021-06-12T16:41:08Z")

</div>

> [@fredrikekre](#):
>
> Would a wording like
> 
> > This documentation is not for the latest version.
> 
> be better and be applicable in both cases?

Yes, I think it is better and is never misleading.

---

<div class="post-metadata">

**Author:** ![giordano](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/giordano/32/2166_2.png) [@giordano](https://discourse.julialang.org/u/giordano)\
**Post date:** [June 12, 2021, 5:06pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/15 "2021-06-12T17:06:22Z")

</div>

What are the breaking changes in v0.27? I don’t see any in the [ChangeLog](https://github.com/JuliaDocs/Documenter.jl/blob/cf9e4a23193b6500aa1c349cdce19d524f51b5ba/CHANGELOG.md#version-v0270). Also, can we have a v1.0 release as next breaking release so that new features don’t make a minor bump? 🙂

After the rant, thanks for work on the package!

---

<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:** [June 17, 2021, 3:17am UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/16 "2021-06-17T03:17:36Z")

</div>

Small follow-up ANN: [Documenter 0.27.1](https://github.com/JuliaDocs/Documenter.jl/blob/master/CHANGELOG.md#version-v0271) just got tagged. It brings a few fixes to the version warning feature. But as a bigger change, it also now uses @cormullion’s [JuliaMono](https://juliamono.netlify.app/) as the default monospace font!

Note that if you have `Documenter = "0.27"` in your `docs/Project.toml`, the update should happen automatically.

---

<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:** [June 17, 2021, 3:35am UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/17 "2021-06-17T03:35:11Z")

</div>

> [@giordano](#):
>
> What are the breaking changes in v0.27? I don’t see any in the [ChangeLog](https://github.com/JuliaDocs/Documenter.jl/blob/cf9e4a23193b6500aa1c349cdce19d524f51b5ba/CHANGELOG.md#version-v0270). Also, can we have a v1.0 release as next breaking release so that new features don’t make a minor bump? 🙂

I have been intentionally very conservative with what goes into a patch release. The reason is that with the standard setup the latest patch version gets used automatically on CI, and so it is easy to silently and automatically break the deployed documentation. E.g. in case of 0.27, e.g. the KaTeX library had a major version bump, which might break the rendering of some more complex equations.

As for 1.0 – yes, that would be good. It would allow for a bit more nuance in terms of versioning (more complex docs probably want to restrict to a minor version of Documenter, but simpler ones are probably fine with the standard a major version restriction). But there is a backlog of things that should be done before we commit to 1.0 (e.g. moving the Markdown backend out of Documenter, revising the documentation).

---

<div class="post-metadata">

**Author:** ![odow](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/odow/32/28685_2.png) [@odow](https://discourse.julialang.org/u/odow)\
**Post date:** [June 21, 2021, 8:40am UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/18 "2021-06-21T08:40:41Z")

</div>

> [@pfitzseb](#):
>
> Note that you’ll need to figure out which of these changes to check in

Maybe edit this text (or make it bold)? I got bitten by it:

> <https://github.com/jump-dev/JuMP.jl/pull/2631#issuecomment-864821577>
>
> Kind of. You wouldn't get the warning if \`stable\` had been build with 0.27, yes.… 
> But when using \`OutdatedWarning.generate\` you need to figure out which changes to check in yourself -- that warning is completely unconditional.

---

<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:** [July 7, 2021, 11:54am UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/19 "2021-07-07T11:54:35Z")

</div>

Documenter [0.27.2](https://github.com/JuliaDocs/Documenter.jl/releases/tag/v0.27.2) ([changelog](https://github.com/JuliaDocs/Documenter.jl/blob/v0.27.2/CHANGELOG.md)) and [0.27.3](https://github.com/JuliaDocs/Documenter.jl/releases/tag/v0.27.3) ([changelog](https://github.com/JuliaDocs/Documenter.jl/blob/v0.27.3/CHANGELOG.md)) are released with miscellaneous fixes.

I just wanted to highlight one new feature which is the ability to deploy to the “root” instead of to a versioned folder. Previously it was only possible to deploy to a subfolder, e.g. `v1.2.3` or `latest`, but that only makes sense for versioned project (such as packages). This feature is used already for [https://juliadocs.github.io/](https://juliadocs.github.io/) (which thus previously was deployed to [https://juliadocs.github.io/latest](https://juliadocs.github.io/latest)).

---

<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:** [July 27, 2021, 12:56pm UTC](https://discourse.julialang.org/t/ann-documenter-0-27/62726/20 "2021-07-27T12:56:24Z")

</div>

Documenter versions [0.27.4](https://github.com/JuliaDocs/Documenter.jl/releases/tag/v0.27.4) ([changelog](https://github.com/JuliaDocs/Documenter.jl/blob/v0.27.4/CHANGELOG.md)) and [0.27.5](https://github.com/JuliaDocs/Documenter.jl/releases/tag/v0.27.5) ([changelog](https://github.com/JuliaDocs/Documenter.jl/blob/v0.27.5/CHANGELOG.md)) are released.

I want to highlight some new features that I personally think are pretty neat:

- `@repl` and `@example` blocks now support colored text output much in a terminal (thanks @kimikage).
- Experimental support for pregeneration of code syntax highlighting (e.g. during build instead of “live” in the browser). At the cost of slightly larger HTML pages users without JavaScript enabled can now also enjoy code syntax highlighting. However, the feature I am most excited about is that it makes it possible to use an [improved highlighter](https://fredrikekre.se/posts/highlight-julia/).
- Varions fixes to `@repl` and `@example` blocks: correct `LineNumberNodes` for more realistic output from e.g. logging macros and error messages, better scrubbing of the sandbox module used by Documenter to evaluate code.

[Next page](https://discourse.julialang.org/t/ann-documenter-0-27/62726.md?page=2)