Add warning for outdated docs

CHANGELOG.md

@@ -10,6 +10,8 @@
 
 * ![Enhancement][badge-enhancement] In the HTML output, the site name at the top of the sidebar now also links back to the main page of the documentation (just like the logo). ([#1553][github-1553])
 
+* ![Enhancement][badge-enhancement] The generated HTML sites can now detect if the version the user is browsing is not for the latest version of the package and display a notice box to the user with a link to the latest version. In addition, the pages get a `noindex` tag which should aid in removing outdated versions from search engine results. ([#1302][github-1302], [#1449][github-1449], [#1577][github-1577])
+
 * ![Bugfix][badge-bugfix] A bad `repo` argument to `deploydocs` containing a protocol now throws an error instead of being misinterpreted. ([#1531][github-1531], [#1533][github-1533])
 
 * ![Bugfix][badge-bugfix] SVG images generated by `@example` blocks are now properly scaled to page width by URI-encoding the images, instead of directly embedding the SVG tags into the HTML. ([#1537][github-1537], [#1538][github-1538])
@@ -711,6 +713,7 @@
 [github-1295]: https://github.com/JuliaDocs/Documenter.jl/pull/1295
 [github-1298]: https://github.com/JuliaDocs/Documenter.jl/pull/1298
 [github-1299]: https://github.com/JuliaDocs/Documenter.jl/pull/1299
+[github-1302]: https://github.com/JuliaDocs/Documenter.jl/issues/1302
 [github-1311]: https://github.com/JuliaDocs/Documenter.jl/pull/1311
 [github-1307]: https://github.com/JuliaDocs/Documenter.jl/pull/1307
 [github-1310]: https://github.com/JuliaDocs/Documenter.jl/pull/1310
@@ -746,6 +749,7 @@
 [github-1438]: https://github.com/JuliaDocs/Documenter.jl/issues/1438
 [github-1448]: https://github.com/JuliaDocs/Documenter.jl/pull/1448
 [github-1440]: https://github.com/JuliaDocs/Documenter.jl/pull/1440
+[github-1449]: https://github.com/JuliaDocs/Documenter.jl/issues/1449
 [github-1452]: https://github.com/JuliaDocs/Documenter.jl/pull/1452
 [github-1456]: https://github.com/JuliaDocs/Documenter.jl/pull/1456
 [github-1462]: https://github.com/JuliaDocs/Documenter.jl/issues/1462
@@ -785,6 +789,7 @@
 [github-1556]: https://github.com/JuliaDocs/Documenter.jl/issues/1556
 [github-1557]: https://github.com/JuliaDocs/Documenter.jl/pull/1557
 [github-1567]: https://github.com/JuliaDocs/Documenter.jl/pull/1567
+[github-1577]: https://github.com/JuliaDocs/Documenter.jl/pull/1577
 
 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079
 [julia-39841]: https://github.com/JuliaLang/julia/pull/39841

assets/html/scss/documenter/components/_admonition.scss

@@ -10,7 +10,7 @@ $admonition-body-color: () !default;
 $admonition-header-background: () !default;
 $admonition-header-color: () !default;
 @each $name, $color in $admonition-colors {
-  $bg: lighten-color($color, 4);
+  $bg: lighten-color($color, 5);
   @if not map-has-key($admonition-header-background, $name) {
     $admonition-header-background: map-merge($admonition-header-background, ($name: $color)) !global;
   }

assets/html/scss/documenter/components/_all.scss

@@ -1,3 +1,4 @@
 @import "admonition";
 @import "docstring";
 @import "example";
+@import "warner";

assets/html/scss/documenter/components/_warner.scss

@@ -0,0 +1,30 @@
+// outdated-docs warning overlay
+.outdated-warning-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  box-shadow: 0 0 10px rgba(0,0,0,0.3);
+  z-index: 999;
+  background-color: map-get($admonition-background, 'danger');
+  color: map-get($admonition-body-color, 'danger');
+  border-bottom: 3px solid map-get($admonition-header-background, 'danger');
+  padding: 10px 35px;
+  text-align: center;
+  font-size: 15px;
+
+  .outdated-warning-closer {
+    position: absolute;
+    top: calc(50% - 10px);
+    right: 18px;
+    cursor: pointer;
+    width: 12px;
+  }
+
+  a {
+    color: $link;
+    &:hover {
+      color: $link-hover;
+    }
+  }
+}

assets/html/warner.js

@@ -0,0 +1,44 @@
+function maybeAddWarning () {
+    // DOCUMENTER_NEWEST is defined in versions.js, DOCUMENTER_CURRENT_VERSION in siteinfo.js.
+    // If either of these are undefined something went horribly wrong, so we abort.
+    if (window.DOCUMENTER_NEWEST === undefined || window.DOCUMENTER_CURRENT_VERSION === undefined) {
+        return
+    };
+
+    // Current version is not a version number, so we can't tell if it's the newest version. Abort.
+    if (!/v(\d+\.)*\d+/.test(window.DOCUMENTER_CURRENT_VERSION)) {
+        return
+    };
+
+    // Current version is newest version, so no need to add a warning.
+    if (window.DOCUMENTER_NEWEST === window.DOCUMENTER_CURRENT_VERSION) {
+        return
+    };
+
+    // Add a noindex meta tag (unless one exists) so that search engines don't index this version of the docs.
+    if (document.body.querySelector('meta[name="robots"]') === null) {
+        const meta = document.createElement('meta');
+        meta.name = 'robots';
+        meta.content = 'noindex';
+
+        document.getElementsByTagName('head')[0].appendChild(meta);
+    };
+
+    const div = document.createElement('div');
+    div.classList.add('outdated-warning-overlay');
+    const closer = document.createElement('button');
+    closer.classList.add('outdated-warning-closer', 'delete');
+    closer.addEventListener('click', function () {
+        document.body.removeChild(div);
+    });
+    const href = window.documenterBaseURL + '/../' + window.DOCUMENTER_NEWEST;
+    div.innerHTML = 'This is an old version of the documentation. <br> <a href="' + href + '">Go to the newest version</a>.';
+    div.appendChild(closer);
+    document.body.appendChild(div);
+};
+
+if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', maybeAddWarning);
+} else {
+    maybeAddWarning();
+};

docs/src/lib/public.md

@@ -37,4 +37,5 @@ DocMeta.setdocmeta!
 ```@docs
 DocumenterTools.generate
 DocumenterTools.genkeys
+DocumenterTools.OutdatedWarning.generate
 ```

src/Documenter.jl

@@ -586,7 +586,7 @@ function git_push(
 
         # Create the versions.js file containing a list of `entries`.
         # This must always happen after the folder copying.
-        Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries)
+        Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries, symlinks)
 
         # generate the symlinks, make sure we don't overwrite devurl
         cd(dirname) do

src/Writers/HTMLWriter.jl

@@ -60,6 +60,9 @@ using ...Utilities.MDFlatten
 
 export HTML
 
+"Data attribute for the script inserting a wraning for outdated docs."
+const OUTDATED_VERSION_ATTR = "data-outdated-warner"
+
 "List of Documenter native themes."
 const THEMES = ["documenter-light", "documenter-dark"]
 "The root directory of the HTML assets."
@@ -339,6 +342,9 @@ value is `"en"`.
 the page navigation. Defaults to `"Powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)
 and the [Julia Programming Language](https://julialang.org/)."`.
 
+**`warn_outdated`** inserts a warning if the current page is not the newest version of the
+documentation.
+
 # Default and custom assets
 
 Documenter copies all files under the source directory (e.g. `/docs/src/`) over
@@ -383,6 +389,7 @@ struct HTML <: Documenter.Writer
     mathengine    :: Union{MathEngine,Nothing}
     footer        :: Union{Markdown.MD, Nothing}
     lang          :: String
+    warn_outdated :: Bool
 
     function HTML(;
             prettyurls    :: Bool = true,
@@ -399,6 +406,7 @@ struct HTML <: Documenter.Writer
             # deprecated keywords
             edit_branch   :: Union{String, Nothing, Default} = Default(nothing),
             lang          :: String = "en",
+            warn_outdated :: Bool = true
         )
         collapselevel >= 1 || throw(ArgumentError("collapselevel must be >= 1"))
         assets = map(assets) do asset
@@ -426,7 +434,7 @@ struct HTML <: Documenter.Writer
         end
         isa(edit_link, Default) && (edit_link = edit_link[])
         new(prettyurls, disable_git, edit_link, canonical, assets, analytics,
-            collapselevel, sidebar_sitename, highlights, mathengine, footer, lang)
+            collapselevel, sidebar_sitename, highlights, mathengine, footer, lang, warn_outdated)
     end
 end
 
@@ -567,14 +575,15 @@ mutable struct HTMLContext
     scripts :: Vector{String}
     documenter_js :: String
     themeswap_js :: String
+    warner_js :: String
     search_js :: String
     search_index :: Vector{SearchRecord}
     search_index_js :: String
     search_navnode :: Documents.NavNode
     footnotes :: Vector{Markdown.Footnote}
 end
 
-HTMLContext(doc, settings=HTML()) = HTMLContext(doc, settings, [], "", "", "", [], "", Documents.NavNode("search", "Search", nothing), [])
+HTMLContext(doc, settings=HTML()) = HTMLContext(doc, settings, [], "", "", "", "", [], "", Documents.NavNode("search", "Search", nothing), [])
 
 function SearchRecord(ctx::HTMLContext, navnode; fragment="", title=nothing, category="page", text="")
     page_title = mdflatten(pagetitle(ctx, navnode))
@@ -636,6 +645,7 @@ function render(doc::Documents.Document, settings::HTML=HTML())
     ctx = HTMLContext(doc, settings)
     ctx.search_index_js = "search_index.js"
     ctx.themeswap_js = copy_asset("themeswap.js", doc)
+    ctx.warner_js = copy_asset("warner.js", doc)
 
     # Generate documenter.js file with all the JS dependencies
     ctx.documenter_js = "assets/documenter.js"
@@ -839,6 +849,7 @@ function render_head(ctx, navnode)
         title(page_title),
 
         analytics_script(ctx.settings.analytics),
+        warning_script(src, ctx),
 
         canonical_link_element(ctx.settings.canonical, pretty_url(ctx, src)),
 
@@ -901,6 +912,13 @@ analytics_script(tracking_id::AbstractString) =
         """
     )
 
+function warning_script(src, ctx)
+    if ctx.settings.warn_outdated
+        return Tag(:script)[Symbol(OUTDATED_VERSION_ATTR), :src => relhref(src, ctx.warner_js)]()
+    end
+    return Tag(Symbol("#RAW#"))("")
+end
+
 function canonical_link_element(canonical_link, src)
    @tags link
    if canonical_link === nothing
@@ -1286,13 +1304,26 @@ function expand_versions(dir, versions)
 end
 
 # write version file
-function generate_version_file(versionfile::AbstractString, entries)
+function generate_version_file(versionfile::AbstractString, entries, symlinks = [])
     open(versionfile, "w") do buf
         println(buf, "var DOC_VERSIONS = [")
         for folder in entries
             println(buf, "  \"", folder, "\",")
         end
         println(buf, "];")
+
+        # The first element in entries corresponds to the latest version, but is usually not the full version
+        # number. So this essentially follows the symlinks that will be generated to figure out the full
+        # version number (stored in DOCUMENTER_CURRENT_VERSION in siteinfo.js).
+        # Every symlink points to a directory, so this doesn't need to be recursive.
+        newest = first(entries)
+        for s in symlinks
+            if s.first == newest
+                newest = s.second
+                break
+            end
+        end
+        println(buf, "var DOCUMENTER_NEWEST = \"$(newest)\";")
     end
 end
 
@@ -1788,10 +1819,10 @@ function mdconvert(d::Dict{MIME,Any}, parent; kwargs...)
                 svg = replace(svg, "\'" => "%27")
                 sep = "'"
             end
-            
+
             out = Documents.RawHTML(string("<img src=", sep, "data:image/svg+xml;utf-8,", svg, sep, "/>"))
         end
-        
+
     elseif haskey(d, MIME"image/png"())
         out = Documents.RawHTML(string("<img src=\"data:image/png;base64,", d[MIME"image/png"()], "\" />"))
     elseif haskey(d, MIME"image/webp"())

test/examples/tests.jl

@@ -36,8 +36,10 @@ end
             # Test existence of some HTML elements
             man_style_html = String(read(joinpath(build_dir, "man", "style", "index.html")))
             @test occursin("is-category-myadmonition", man_style_html)
+            @test occursin(Documenter.Writers.HTMLWriter.OUTDATED_VERSION_ATTR, man_style_html)
 
             index_html = read(joinpath(build_dir, "index.html"), String)
+            @test occursin(Documenter.Writers.HTMLWriter.OUTDATED_VERSION_ATTR, index_html)
             @test occursin("documenter-example-output", index_html)
             @test occursin("1392-test-language", index_html)
             @test !occursin("1392-extra-info", index_html)