From 706ea3fc5f1536878efde3336ef260f75b6adcc1 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 11:15:11 -0500 Subject: [PATCH 01/15] iniital untested implementation --- src/writer.jl | 65 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 14 deletions(-) diff --git a/src/writer.jl b/src/writer.jl index 9e29bfd9..c4de2769 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -8,8 +8,8 @@ import Markdown """ MarkdownVitepress(; repo, devbranch, devurl, kwargs...) -This is the main entry point for the Vitepress Markdown writer. - +This is the main entry point for the Vitepress Markdown writer. + It is a config which can be passed to the `format` keyword argument in `Documenter.makedocs`, and causes it to emit a Vitepress site. !!! tip "Quick start" @@ -45,13 +45,27 @@ Base.@kwdef struct MarkdownVitepress <: Documenter.Writer """The path to which the Markdown files will be output. Defaults to `\$build/.documenter`.""" md_output_path::String = ".documenter" """ - Determines whether to clean up the Markdown assets after build, i.e., whether to remove the contents of `md_output_path` after the Vitepress site is built. + Determines whether to clean up the Markdown assets after build, i.e., whether to remove the contents of `md_output_path` after the Vitepress site is built. Options are: - `nothing`: **Default**. Only remove the contents of `md_output_path` if the documentation will deploy, to save space. - `true`: Removes the contents of `md_output_path` after the Vitepress site is built. - `false`: Does not remove the contents of `md_output_path` after the Vitepress site is built. """ clean_md_output::Union{Nothing, Bool} = nothing + """ + Whether insert 200 redirects from https://example.com/page/ to https://example.com/page. + + Defaults to `false`. This is useful for transitioning from Documenter.jl which uses + trailing slashes for its canonical urls by default. + """ + redirect_trailing_slash::Bool = false + + function MarkdownVitepress(args...) + args[10] && !args[6] && throw(ArgumentError( + "redirect_trailing_slash can only be true if build_vitepress is also true because redirects are insterted after the site is built" + )) + new(args...) + end end # return the same file with the extension changed to .md @@ -66,13 +80,13 @@ This function takes the filename `file`, and returns a file path in the `mdfolde function docpath(file, builddir, mdfolder) path = relpath(file, builddir) filename = mdext(path) - return joinpath(builddir, mdfolder, filename) + return joinpath(builddir, mdfolder, filename) end """ render(args...) -This is the main entry point and recursive function to render a Documenter document to +This is the main entry point and recursive function to render a Documenter document to Markdown in the Vitepress flavour. It is called by `Documenter.build` and should not be called directly. @@ -114,7 +128,7 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi file_relpath = relpath(file, joinpath(builddir, settings.md_output_path, "assets")) cp(joinpath(builddir, settings.md_output_path, "assets", file_relpath), joinpath(builddir, settings.md_output_path, "public", file_relpath)) end - end + end if any(favicon_files) for file in files[favicon_files] file_relpath = relpath(file, joinpath(builddir, settings.md_output_path, "assets")) @@ -146,7 +160,7 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi devurl = settings.devurl, push_preview=true, ) - + # from `vitepress_config.jl` modify_config_file(doc, settings, deploy_decision) @@ -181,7 +195,7 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi rm(joinpath(dirname(builddir), "package-lock.json")) end end - # This is only useful if placed in the root of the `docs` folder, and we don't + # This is only useful if placed in the root of the `docs` folder, and we don't # have any names which conflict with Jekyll (beginning with _ or .) in any case. # touch(joinpath(builddir, "final_site", ".nojekyll")) @@ -201,6 +215,29 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi @info "DocumenterVitepress: Markdown output cleaned up. Folder looks like: $(readdir(doc.user.build))" end + if settings.redirect_trailing_slash + @info "DocumenterVitepress: inserting 200 redirects from https://example.com/page/ to https://example.com/page because `redirect_trailing_slash` is true." + for (root, dirs, files) in walkdir(builddir) + for file in files + name, ext = splitext(file) + if ext === ".html" && name ∉ ("404", "index") + dir = joinpath(root, name) + if !isdir(dir) + mkdir(dir) + url = "https://"*normpath(joinpath(settings.deploy_url, root, name)) + open(joinpath(dir, "index.html"), "w") do io + write(io, """ + + + Redirecting to $url + + """) + end + end + end + end + end + end else @info """ DocumenterVitepress: did not build Vitepress site because `build_vitepress` was set to `false`. @@ -296,7 +333,7 @@ function renderdoc(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST. if url !== nothing # This is how Documenter does it: # push!(ret.nodes, a[".docs-sourcelink", :target=>"_blank", :href=>url]("source")) - # so clearly we should be inserting some form of HTML tag here, + # so clearly we should be inserting some form of HTML tag here, # and defining its rendering in CSS? # TODO: switch to Documenter style here println(io, "\n", "[source]($url)", "\n") @@ -361,9 +398,9 @@ function join_multiblock(mcb::Documenter.MultiCodeBlock) for thing in mcb.content # reset the buffer and push the old code block if thing.language != current_language - # Remove this if statement if you want to + # Remove this if statement if you want to # include empty code blocks in the output. - if isempty(thing.code) + if isempty(thing.code) current_string *= "\n\n" continue end @@ -459,7 +496,7 @@ function render_mime(io::IO, mime::MIME"image/svg+xml", node, element, page, doc # Additionally, Vitepress complains about the XML version and encoding string below, # so we just remove this bad hombre! bad_hombre_string = "" |> lowercase - location = findfirst(bad_hombre_string, lowercase(image_text)) + location = findfirst(bad_hombre_string, lowercase(image_text)) if !isnothing(location) # couldn't figure out how to do this in one line - maybe regex? A question for later though. image_text = replace(image_text, image_text[location] => "") end @@ -682,7 +719,7 @@ function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Nod # Main.@infiltrate print(io, "\$", math.math, "\$") end -# Display math +# Display math function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Node, math::MarkdownAST.DisplayMath, page, doc; kwargs...) # Main.@infiltrate println(io) @@ -726,7 +763,7 @@ function render(io::IO, mime::MIME"text/plain", node::Documenter.MarkdownAST.Nod end end # We create this IOBuffer in order to render to it. - iob = IOBuffer() + iob = IOBuffer() # This will eventually hold the rendered table cells as Strings. cell_strings = Vector{Vector{String}}() current_row_vec = String[] From d52fe0bee61e766ce7a196fcf719ea3110480b1c Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 11:19:50 -0500 Subject: [PATCH 02/15] add superficial tests --- Project.toml | 11 +++++++++-- test/runtests.jl | 5 +++++ 2 files changed, 14 insertions(+), 2 deletions(-) create mode 100644 test/runtests.jl diff --git a/Project.toml b/Project.toml index 39eefc28..cf8dadd4 100644 --- a/Project.toml +++ b/Project.toml @@ -14,9 +14,16 @@ NodeJS_20_jll = "c7aee132-11e1-519c-8219-0a43005e73c2" REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb" [compat] -julia = "1.6" ANSIColoredPrinters = "0.0.1" -Documenter = "1" DocStringExtensions = "0.9" +Documenter = "1" IOCapture = "0.2" NodeJS_20_jll = "20" +Test = "1.11.0" +julia = "1.6" + +[extras] +Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" + +[targets] +test = ["Test"] diff --git a/test/runtests.jl b/test/runtests.jl new file mode 100644 index 00000000..2a3ee55f --- /dev/null +++ b/test/runtests.jl @@ -0,0 +1,5 @@ +using Test, DocumenterVitepress + +@test DocumenterVitepress.MarkdownVitepress(; repo = "...", devbranch = "...", devurl = "...") isa DocumenterVitepress.MarkdownVitepress +@test_throws ArgumentError DocumenterVitepress.MarkdownVitepress(; repo = "...", devbranch = "...", devurl = "...", + build_vitepress = false, redirect_trailing_slash = true) From 476cdd1a5b7605ed30ecdf4f0db159634f827c15 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 11:56:16 -0500 Subject: [PATCH 03/15] print --- src/writer.jl | 1 + 1 file changed, 1 insertion(+) diff --git a/src/writer.jl b/src/writer.jl index c4de2769..9d68a16c 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -224,6 +224,7 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi dir = joinpath(root, name) if !isdir(dir) mkdir(dir) + println(((settings.deploy_url, root, name))) url = "https://"*normpath(joinpath(settings.deploy_url, root, name)) open(joinpath(dir, "index.html"), "w") do io write(io, """ From 3708e9ff67ae45d278b6036bb0c96d7b6b07c3cc Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 12:01:59 -0500 Subject: [PATCH 04/15] deug --- src/writer.jl | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/writer.jl b/src/writer.jl index 9d68a16c..eb57a1b0 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -224,8 +224,9 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi dir = joinpath(root, name) if !isdir(dir) mkdir(dir) - println(((settings.deploy_url, root, name))) - url = "https://"*normpath(joinpath(settings.deploy_url, root, name)) + println(((settings.deploy_url, root, builddir, name))) + url = "https://"*normpath(joinpath(settings.deploy_url, relpath(root, builddir), name)) + println(url) open(joinpath(dir, "index.html"), "w") do io write(io, """ From ece1e31bb104a8050097f4f527bdb9c6cdb832ad Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 12:10:14 -0500 Subject: [PATCH 05/15] rel url to avoid needing knowledge that we only have at deploy-time --- src/writer.jl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/writer.jl b/src/writer.jl index eb57a1b0..512dff03 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -231,9 +231,9 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi write(io, """ - Redirecting to $url - - """) + Redirecting to ../$name + + """) end end end From 4f52871452115cdb10bed0a655cd8d0e61f25f79 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 12:26:25 -0500 Subject: [PATCH 06/15] keep fragments --- src/writer.jl | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/writer.jl b/src/writer.jl index 512dff03..e3a882df 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -232,8 +232,16 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi Redirecting to ../$name - + + """) + # This uses a relative canonical link which is bad form, but + # oh well. We don't have access to the full URL until deploy + # time. end end end From 7ea54c5886bb25d3c7c373ffb2ba473891216dd1 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 12:38:32 -0500 Subject: [PATCH 07/15] remove stray tags --- src/writer.jl | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/writer.jl b/src/writer.jl index e3a882df..a1276a17 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -230,9 +230,6 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi open(joinpath(dir, "index.html"), "w") do io write(io, """ - - Redirecting to ../$name - @@ -239,6 +238,10 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi # This uses a relative canonical link which is bad form, but # oh well. We don't have access to the full URL until deploy # time. + # + # The script is equivalent to + # `` + # but keeps fragments end end end From 8d492349ae037cc0f354de7547e932d23c2efb64 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 12:43:07 -0500 Subject: [PATCH 10/15] mini-minify --- src/writer.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/writer.jl b/src/writer.jl index 5b84e85c..96b2d10f 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -231,8 +231,8 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi write(io, """ """) # This uses a relative canonical link which is bad form, but From e9ba132dd0d3aae22bbf05aac76aeebef03c3a16 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 12:56:50 -0500 Subject: [PATCH 11/15] add fallbacks (probably broken) --- src/writer.jl | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/writer.jl b/src/writer.jl index 96b2d10f..c029bc1a 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -234,6 +234,8 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi const u = new URL(window.location.href); window.location.replace(u.origin + u.pathname.slice(0,-1) + u.search + u.hash); + Redirecting to ..$name + """) # This uses a relative canonical link which is bad form, but # oh well. We don't have access to the full URL until deploy From a7f511c73295ea992021075926f4db7877c3b71c Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 13:01:46 -0500 Subject: [PATCH 12/15] give js 1 second to perform the refresh before fallback --- src/writer.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/writer.jl b/src/writer.jl index c029bc1a..b2c6389e 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -235,7 +235,7 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi window.location.replace(u.origin + u.pathname.slice(0,-1) + u.search + u.hash); Redirecting to ..$name - + """) # This uses a relative canonical link which is bad form, but # oh well. We don't have access to the full URL until deploy From cb7785685b5d0b169e753c322ed487e766d5cd21 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 13:02:22 -0500 Subject: [PATCH 13/15] Revert "give js 1 second to perform the refresh before fallback" This reverts commit a7f511c73295ea992021075926f4db7877c3b71c. --- src/writer.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/writer.jl b/src/writer.jl index b2c6389e..c029bc1a 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -235,7 +235,7 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi window.location.replace(u.origin + u.pathname.slice(0,-1) + u.search + u.hash); Redirecting to ..$name - + """) # This uses a relative canonical link which is bad form, but # oh well. We don't have access to the full URL until deploy From 40cee84bacf4b2a508db71c226f7b191f029b169 Mon Sep 17 00:00:00 2001 From: Lilith Orion Hafner Date: Sun, 10 Mar 2024 13:06:26 -0500 Subject: [PATCH 14/15] more comment --- src/writer.jl | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/writer.jl b/src/writer.jl index c029bc1a..2b4042b5 100644 --- a/src/writer.jl +++ b/src/writer.jl @@ -237,13 +237,16 @@ function render(doc::Documenter.Document, settings::MarkdownVitepress=MarkdownVi Redirecting to ..$name """) + # The script is equivalent to + # `` + # but keeps fragments. If Javascript fails for whatever + # reason, the meta http-equiv will proc, dropping fragments + # If that, too fails, there's an ordinary, human readable + # relative link. + # # This uses a relative canonical link which is bad form, but # oh well. We don't have access to the full URL until deploy # time. - # - # The script is equivalent to - # `` - # but keeps fragments end end end From 0849ac0ae99d9d2ad38331e4f0567ba5900bba46 Mon Sep 17 00:00:00 2001 From: Anshul Singhvi Date: Tue, 2 Apr 2024 10:38:30 -0400 Subject: [PATCH 15/15] Update Test compat to 1 --- Project.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Project.toml b/Project.toml index 707ac7a2..c6dbe1ed 100644 --- a/Project.toml +++ b/Project.toml @@ -19,7 +19,7 @@ DocStringExtensions = "0.9" Documenter = "1" IOCapture = "0.2" NodeJS_20_jll = "20" -Test = "1.11.0" +Test = "1" julia = "1.6" [extras]