Add "Powered by ..." message to footer (#1365)

CHANGELOG.md

@@ -6,6 +6,8 @@
 
 * ![Enhancement][badge-enhancement] The output text boxes of `@example` blocks are now style differently from the code blocks, to make it easier to visually distinguish between the input and output. ([#1026][github-1026], [#1357][github-1357], [#1360][github-1360])
 
+* ![Enhancement][badge-enhancement] The generated HTML site now displays a footer by default that mentions Julia and Documenter. This can be customized or disabled by passing the `footer` keyword to `Documeter.HTML`. ([#1184][github-1184], [#1365][github-1365])
+
 ## Version `v0.25.0`
 
 * ![Enhancement][badge-enhancement] When deploying with `deploydocs`, any SSH username can now be used (not just `git`), by prepending `username@` to the repository URL in the `repo` argument. ([#1285][github-1285])
@@ -563,6 +565,7 @@
 [github-1171]: https://github.com/JuliaDocs/Documenter.jl/pull/1171
 [github-1173]: https://github.com/JuliaDocs/Documenter.jl/pull/1173
 [github-1180]: https://github.com/JuliaDocs/Documenter.jl/pull/1180
+[github-1184]: https://github.com/JuliaDocs/Documenter.jl/issues/1184
 [github-1186]: https://github.com/JuliaDocs/Documenter.jl/pull/1186
 [github-1189]: https://github.com/JuliaDocs/Documenter.jl/pull/1189
 [github-1194]: https://github.com/JuliaDocs/Documenter.jl/pull/1194
@@ -598,6 +601,7 @@
 [github-1355]: https://github.com/JuliaDocs/Documenter.jl/pull/1355
 [github-1357]: https://github.com/JuliaDocs/Documenter.jl/pull/1357
 [github-1360]: https://github.com/JuliaDocs/Documenter.jl/pull/1360
+[github-1365]: https://github.com/JuliaDocs/Documenter.jl/pull/1365
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

assets/html/scss/documenter/layout/_main.scss

@@ -108,6 +108,7 @@
 
  .docs-footer {
  display: flex;
+ flex-wrap: wrap;
  margin-left: 0;
  margin-right: 0;
  border-top: 1px solid $border;
@@ -125,6 +126,17 @@
  .docs-footer-nextpage {
  text-align: right;
  }
+
+ .flexbox-break {
+ flex-basis: 100%;
+ height: 0;
+ }
+
+ .footer-message {
+ font-size: 0.8em;
+ margin: 0.5em auto 0 auto;
+ text-align: center;
+ }
  }
  }
 }

src/Writers/HTMLWriter.jl

@@ -7,8 +7,8 @@ A module for rendering `Document` objects to HTML.
 [`Documenter.makedocs`](@ref): `authors`, `pages`, `sitename`, `version`.
 The behavior of [`HTMLWriter`](@ref) can be further customized by setting the `format`
 keyword of [`Documenter.makedocs`](@ref) to a [`HTML`](@ref), which accepts the following
-keyword arguments: `analytics`, `assets`, `canonical`, `disable_git`, `edit_link` and
-`prettyurls`.
+keyword arguments: `analytics`, `assets`, `canonical`, `disable_git`, `edit_link`,
+`prettyurls`, `collapselevel`, `sidebar_sitename`, `highlights`, `mathengine` and `footer`.
 
 **`sitename`** is the site's title displayed in the title bar and at the top of the
 *navigation menu. This argument is mandatory for [`HTMLWriter`](@ref).
@@ -283,6 +283,10 @@ passing options to the [`KaTeX`](@ref) or [`MathJax`](@ref) constructors.
 
 **`lang`** can be used to specify the language tag of each HTML page. Default is `"en"`.
 
+**`footer`** can be a valid single-line markdown `String` or `nothing` and is displayed below
+the page navigation. Defaults to `"Powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)
+and the [Julia Programming Language](https://julialang.org/)."`.
+
 # Default and custom assets
 
 Documenter copies all files under the source directory (e.g. `/docs/src/`) over
@@ -325,6 +329,7 @@ struct HTML <: Documenter.Writer
  sidebar_sitename :: Bool
  highlights :: Vector{String}
  mathengine :: Union{MathEngine,Nothing}
+ footer :: Union{Markdown.MD, Nothing}
  lang :: String
 
  function HTML(;
@@ -336,8 +341,9 @@ struct HTML <: Documenter.Writer
  analytics :: String = "",
  collapselevel :: Integer = 2,
  sidebar_sitename :: Bool = true,
- highlights :: Vector{String} = String[],
- mathengine :: Union{MathEngine,Nothing} = KaTeX(),
+ highlights :: Vector{String} = String[],
+ mathengine :: Union{MathEngine,Nothing} = KaTeX(),
+ footer :: Union{String, Nothing} = "Powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) and the [Julia Programming Language](https://julialang.org/).",
  # deprecated keywords
  edit_branch :: Union{String, Nothing, Default} = Default(nothing),
  lang :: String = "en",
@@ -360,9 +366,15 @@ struct HTML <: Documenter.Writer
  if isa(edit_link, Symbol) && (edit_link !== :commit)
  throw(ArgumentError("Invalid symbol (:$edit_link) passed to edit_link."))
  end
+ if footer !== nothing
+ footer = Markdown.parse(footer)
+ if !(length(footer.content) == 1 && footer.content[1] isa Markdown.Paragraph)
+ throw(ArgumentError("footer must be a single-line markdown compatible string."))
+ end
+ end
  isa(edit_link, Default) && (edit_link = edit_link[])
  new(prettyurls, disable_git, edit_link, canonical, assets, analytics,
- collapselevel, sidebar_sitename, highlights, mathengine, lang)
+ collapselevel, sidebar_sitename, highlights, mathengine, footer, lang)
  end
 end
 
@@ -1058,7 +1070,22 @@ function render_footer(ctx, navnode)
  link = a[".docs-footer-nextpage", :href => navhref(ctx, navnode.next, navnode)](title, " »")
  push!(navlinks, link)
  end
- return isempty(navlinks) ? "" : nav[".docs-footer"](navlinks)
+
+ linebreak = div[".flexbox-break"]()
+ footer_content = ctx.settings.footer
+
+ nav_children = []
+ if !isempty(navlinks)
+ push!(nav_children, navlinks, linebreak)
+ end
+
+ if footer_content !== nothing
+ footer_container = domify(ctx, navnode, footer_content)
+ push!(first(footer_container).attributes, :class => "footer-message")
+ push!(nav_children, footer_container)
+ end
+
+ return nav[".docs-footer"](nav_children...)
 end
 
 # Article (page contents)

test/examples/make.jl

@@ -195,6 +195,7 @@ examples_html_doc = if "html" in EXAMPLE_BUILDS
  ),
  ))),
  highlights = ["erlang", "erlang-repl"],
+ footer = "This footer has been customized.",
  )
  )
  end
@@ -221,6 +222,7 @@ examples_html_local_doc = if "html-local" in EXAMPLE_BUILDS
  assets = ["assets/custom.css"],
  prettyurls = false,
  edit_branch = nothing,
+ footer = nothing,
  ),
  )
 else

test/htmlwriter.jl

@@ -52,6 +52,10 @@ end
  @test Documenter.HTML() isa Documenter.HTML
  @test_throws ArgumentError Documenter.HTML(collapselevel=-200)
  @test_throws Exception Documenter.HTML(assets=["foo.js", 10])
+ @test_throws ArgumentError Documenter.HTML(footer="foo\n\nbar")
+ @test_throws ArgumentError Documenter.HTML(footer="# foo")
+ @test_throws ArgumentError Documenter.HTML(footer="")
+ @test Documenter.HTML(footer="foo bar [baz](https://github.com)") isa Documenter.HTML
 
  # MathEngine
  let katex = KaTeX()