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
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 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. Usage questions are welcome on Discourse and in the #documentation channel on the Julia Slack.
How do I convince github actions to use .27. I tried putting
[compat]
Documenter = "0.27"
in docs/Project.toml
and the run failed with
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
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?
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â.
Yea, you give the path to the folder where you have checked out the gh-pages branch.
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.
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.
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.
What are the breaking changes in v0.27? I donât see any in the ChangeLog. Also, can we have a v1.0 release as next breaking release so that new features donât make a minor bump?
Small follow-up ANN: Documenter 0.27.1 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 as the default monospace font!
Note that if you have Documenter = "0.27" in your docs/Project.toml, the update should happen automatically.
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).
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/ (which thus previously was deployed to https://juliadocs.github.io/latest).
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.
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.
