Add index.html generation for redirecting to ./stable or ./dev

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Documenter.jl changelog
 
+## Version `v0.27.6`
+* ![Feature][badge-feature] Add support for generating `index.html` to redirect to `dev` or `stable`. The redirected destination is the same as the outdated warning. If there's already user-generated `index.html`, Documenter will not overwrite the file. ([#937][github-937], [#1657][github-1657], [#1658][github-1658])
+
 ## Version `v0.27.5`
 
 * ![Bugfix][badge-bugfix] Fix an error introduced in version `v0.27.4` (PR[#1634][github-1634]) which was triggered by trailing comments in `@eval`/`@repl`/`@example` blocks. ([#1655](github-1655), [#1661](github-1661))

src/Documenter.jl

@@ -607,6 +607,10 @@ function git_push(
             # This must always happen after the folder copying.
             Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries, symlinks)
 
+            # Create the index.html file to redirect ./stable or ./dev.
+            # This must always happen after the folder copying.
+            Writers.HTMLWriter.generate_redirect_file(joinpath(dirname, "index.html"), entries)
+
             # generate the symlinks, make sure we don't overwrite devurl
             cd(dirname) do
                 for kv in symlinks

src/Writers/HTMLWriter.jl

@@ -1405,6 +1405,20 @@ function generate_version_file(versionfile::AbstractString, entries, symlinks =
     end
 end
 
+# write redirect file
+function generate_redirect_file(redirectfile::AbstractString, entries)
+    # The link to the redirected destination is same as outdated-warning. (DOCUMENTER_STABLE)
+
+    comment = "<!--This file is automatically generated by Documenter.jl-->"
+
+    isfile(redirectfile) && !startswith(read(redirectfile, String), comment) && return
+
+    open(redirectfile, "w") do buf
+        println(buf, comment)
+        println(buf, "<meta http-equiv=\"refresh\" content=\"0; url=./$(first(entries))/\"/>")
+    end
+end
+
 function generate_siteinfo_file(dir::AbstractString, version::AbstractString)
     open(joinpath(dir, "siteinfo.js"), "w") do buf
         println(buf, "var DOCUMENTER_CURRENT_VERSION = \"$(version)\";")

test/htmlwriter.jl

@@ -3,7 +3,7 @@ module HTMLWriterTests
 using Test
 using Documenter
 using Documenter: DocSystem
-using Documenter.Writers.HTMLWriter: HTMLWriter, generate_version_file, expand_versions
+using Documenter.Writers.HTMLWriter: HTMLWriter, generate_version_file, generate_redirect_file, expand_versions
 
 function verify_version_file(versionfile, entries)
     @test isfile(versionfile)
@@ -16,6 +16,13 @@ function verify_version_file(versionfile, entries)
     end
 end
 
+function verify_redirect_file(redirectfile, version)
+    @test isfile(redirectfile)
+    content = read(redirectfile, String)
+
+    @test occursin("url=./$(version)/", content)
+end
+
 @testset "HTMLWriter" begin
     @test isdir(HTMLWriter.ASSETS)
     @test isdir(HTMLWriter.ASSETS_SASS)
@@ -104,6 +111,8 @@ end
 
     mktempdir() do tmpdir
         versionfile = joinpath(tmpdir, "versions.js")
+        redirectfile = joinpath(tmpdir, "index.html")
+        devurl = "dev"
         versions = ["stable", "dev",
                     "2.1.1", "v2.1.0", "v2.0.1", "v2.0.0",
                     "1.1.1", "v1.1.0", "v1.0.1", "v1.0.0",
@@ -124,6 +133,8 @@ end
                            "v1.1.1"=>"1.1.1", "v0.1.1"=>"0.1.1"]
         generate_version_file(versionfile, entries)
         verify_version_file(versionfile, entries)
+        generate_redirect_file(redirectfile, entries)
+        verify_redirect_file(redirectfile, "stable")
 
         versions = ["v#"]
         entries, symlinks = expand_versions(tmpdir, versions)
@@ -133,6 +144,8 @@ end
                            "v2.1.1"=>"2.1.1", "v1.1.1"=>"1.1.1", "v0.1.1"=>"0.1.1"]
         generate_version_file(versionfile, entries)
         verify_version_file(versionfile, entries)
+        generate_redirect_file(redirectfile, entries)
+        verify_redirect_file(redirectfile, "v2.1")
 
         versions = ["v#.#.#"]
         entries, symlinks = expand_versions(tmpdir, versions)
@@ -143,6 +156,8 @@ end
                            "v2.0"=>"v2.0.1", "v1.1"=>"1.1.1", "v1.0"=>"v1.0.1", "v0.1"=>"0.1.1"]
         generate_version_file(versionfile, entries)
         verify_version_file(versionfile, entries)
+        generate_redirect_file(redirectfile, entries)
+        verify_redirect_file(redirectfile, "v2.1.1")
 
         versions = ["v^", "devel" => "dev", "foobar", "foo" => "bar"]
         entries, symlinks = @test_logs(
@@ -155,6 +170,8 @@ end
         @test ("devel" => "dev") in symlinks
         generate_version_file(versionfile, entries)
         verify_version_file(versionfile, entries)
+        generate_redirect_file(redirectfile, entries)
+        verify_redirect_file(redirectfile, "v2.1")
 
         versions = ["stable" => "v^", "dev" => "stable"]
         @test_throws ArgumentError expand_versions(tmpdir, versions)