A customizable footer on generated pages #1184

MikeInnes · 2019-11-18T13:21:07Z

Right now Documenter does not take advantage of HTML metadata and keywords. Adding some keywords would help search engines find documentation pages, even when the documentation itself does not explicitly refer to Julia. At a minimum we should add something like "julia programming language" and "package" to pages, along with anything else that seems relevant.

If someone can point to the right place I'd be happy to try and get something working.

mortenpi · 2019-11-18T13:34:52Z

If someone can point to the right place I'd be happy to try and get something working.

Happy to oblige 😄

The <head> tag is created in render_head. Would just have to add the necessary <meta>s there.

Documenter.jl/src/Writers/HTMLWriter.jl

Lines 731 to 779 in 40c0f53

    
           function render_head(ctx, navnode) 
        
               @tags head meta link script title 
        
               src = get_url(ctx, navnode) 
        
               page_title = "$(mdflatten(pagetitle(ctx, navnode))) · $(ctx.doc.user.sitename)" 
        
               css_links = [ 
        
                   google_fonts, 
        
                   fontawesome_css..., 
        
                   katex_css, 
        
               ] 
        
               head( 
        
                   meta[:charset=>"UTF-8"], 
        
                   meta[:name => "viewport", :content => "width=device-width, initial-scale=1.0"], 
        
                   title(page_title), 
        
                   analytics_script(ctx.settings.analytics), 
        
                   canonical_link_element(ctx.settings.canonical, src), 
        
                   # Stylesheets. 
        
                   map(css_links) do each 
        
                       link[:href => each, :rel => "stylesheet", :type => "text/css"] 
        
                   end, 
        
                   script("documenterBaseURL=\"$(relhref(src, "."))\""), 
        
                   script[ 
        
                       :src => requirejs_cdn, 
        
                       Symbol("data-main") => relhref(src, ctx.documenter_js) 
        
                   ], 
        
                   script[:src => relhref(src, "siteinfo.js")], 
        
                   script[:src => relhref(src, "../versions.js")], 
        
                   # Custom user-provided assets. 
        
                   asset_links(src, ctx.settings.assets), 
        
                   # Themes. Note: we reverse the make sure that the default theme (first in the array) 
        
                   # comes as the last <link> tag. 
        
                   map(Iterators.reverse(enumerate(THEMES))) do (i, theme) 
        
                       e = link[".docs-theme-link", 
        
                           :rel => "stylesheet", :type => "text/css", 
        
                           :href => relhref(src, "assets/themes/$(theme).css"), 
        
                           Symbol("data-theme-name") => theme, 
        
                       ] 
        
                       (i == 1) && push!(e.attributes, Symbol("data-theme-primary") => "") 
        
                       return e 
        
                   end, 
        
                   script[:src => relhref(src, ctx.themeswap_js)], 
        
               ) 
        
           end

And it would be perfectly fine to add any additional keywords to HTML too, so that users could define their own additional metadata:

Documenter.jl/src/Writers/HTMLWriter.jl

Lines 316 to 364 in 40c0f53

    
           struct HTML <: Documenter.Writer 
        
               prettyurls    :: Bool 
        
               disable_git   :: Bool 
        
               edit_link     :: Union{String, Symbol, Nothing} 
        
               canonical     :: Union{String, Nothing} 
        
               assets        :: Vector{HTMLAsset} 
        
               analytics     :: String 
        
               collapselevel :: Int 
        
               sidebar_sitename :: Bool 
        
               highlights    :: Vector{String} 
        
               mathengine    :: Union{MathEngine,Nothing} 
        
               function HTML(; 
        
                       prettyurls    :: Bool = true, 
        
                       disable_git   :: Bool = false, 
        
                       edit_link     :: Union{String, Symbol, Nothing, Default} = Default("master"), 
        
                       canonical     :: Union{String, Nothing} = nothing, 
        
                       assets        :: Vector = String[], 
        
                       analytics     :: String = "", 
        
                       collapselevel :: Integer = 2, 
        
                       sidebar_sitename :: Bool = true, 
        
                       highlights :: Vector{String} = String[], 
        
                       mathengine :: Union{MathEngine,Nothing} = KaTeX(), 
        
                       # deprecated keywords 
        
                       edit_branch   :: Union{String, Nothing, Default} = Default(nothing), 
        
                   ) 
        
                   collapselevel >= 1 || throw(ArgumentError("collapselevel must be >= 1")) 
        
                   assets = map(assets) do asset 
        
                       isa(asset, HTMLAsset) && return asset 
        
                       isa(asset, AbstractString) && return HTMLAsset(assetclass(asset), asset, true) 
        
                       error("Invalid value in assets: $(asset) [$(typeof(asset))]") 
        
                   end 
        
                   # Handle edit_branch deprecation 
        
                   if !isa(edit_branch, Default) 
        
                       isa(edit_link, Default) || error("Can't specify edit_branch (deprecated) and edit_link simultaneously") 
        
                       @warn """ 
        
                       The edit_branch keyword is deprecated -- use edit_link instead. 
        
                       Note: `edit_branch = nothing` must be changed to `edit_link = :commit`. 
        
                       """ 
        
                       edit_link = (edit_branch === nothing) ? :commit : edit_branch 
        
                   end 
        
                   if isa(edit_link, Symbol) && (edit_link !== :commit) 
        
                       throw(ArgumentError("Invalid symbol (:$edit_link) passed to edit_link.")) 
        
                   end 
        
                   isa(edit_link, Default) && (edit_link = edit_link[]) 
        
                   new(prettyurls, disable_git, edit_link, canonical, assets, analytics, 
        
                       collapselevel, sidebar_sitename, highlights, mathengine) 
        
               end 
        
           end

MikeInnes · 2019-11-18T13:48:36Z

Thanks a lot, will take a look. Another suggestion that's come up is to get some keywords into the content, perhaps by having a discrete footer that says something like "$X.jl, a package for the Julia Programming Language"; any thoughts on that?

mortenpi · 2019-11-18T14:05:48Z

Another suggestion that's come up is to get some keywords into the content, perhaps by having a discrete footer that says something like "$X.jl, a package for the Julia Programming Language"; any thoughts on that?

We could definitely have an optional footer that the user could populate with some content. But I am slightly hesitant to have it default to a string like that, as it may not be a good default in all situations. But I do see that on the other hand, if it's not there by default, it's probably unlikely that people will add such a line by hand to their packages, and so we don't get any SEO out of it.

MikeInnes · 2019-11-18T14:31:01Z

Yeah, making it optional/customisable seems necessary, and it'd have to be opt-out to get the SEO advantages. My feeling is that as long as it's generic enough, it will be apply and be unobjectionable to most packages, especially given the benefits. Might be worth a straw poll on slack though.

ChrisRackauckas · 2019-11-22T10:50:00Z

Opt-out would be a good idea, because it's pretty harmless and would greatly effect the Julia TIOBE ranking if every page said "Julia programming" because that's the silly thing they chose to look for.

KristofferC · 2019-12-02T19:04:01Z

Just putting these here:

https://blog.timbunce.org/2009/05/17/tiobe-index-is-being-gamed/
http://delphi.org/2008/10/delphi-keeps-climbing/

mortenpi · 2020-06-17T00:19:25Z

From a suggestion by @tkf on Slack: a "powered by" footer would resolve this and does not feel too weird to have in place by default (it would be accurate in all situations). E.g.:

Powered by Documenter.jl & the Julia programming language.

Together with a keyword to HTML to either disable it or provide a custom (Markdown) string.

Side note: I'll dedicate this issue for the footer. We can track <meta> tags in #1321.

mortenpi added the Type: Enhancement label Nov 18, 2019

mortenpi mentioned this issue May 14, 2020

Generate Meta Tag #1321

Open

mortenpi added the Format: HTML Related to the default HTML output label Jun 3, 2020

mortenpi changed the title ~~SEO for documentation~~ A customizable footer on generated pages Jun 17, 2020

mortenpi added the help wanted label Jun 17, 2020

pfitzseb mentioned this issue Jul 15, 2020

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

Merged

4 tasks

mortenpi closed this as completed in #1365 Jul 16, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A customizable footer on generated pages #1184

A customizable footer on generated pages #1184

MikeInnes commented Nov 18, 2019

mortenpi commented Nov 18, 2019

MikeInnes commented Nov 18, 2019

mortenpi commented Nov 18, 2019

MikeInnes commented Nov 18, 2019

ChrisRackauckas commented Nov 22, 2019

KristofferC commented Dec 2, 2019

mortenpi commented Jun 17, 2020

A customizable footer on generated pages #1184

A customizable footer on generated pages #1184

Comments

MikeInnes commented Nov 18, 2019

mortenpi commented Nov 18, 2019

MikeInnes commented Nov 18, 2019

mortenpi commented Nov 18, 2019

MikeInnes commented Nov 18, 2019

ChrisRackauckas commented Nov 22, 2019

KristofferC commented Dec 2, 2019

mortenpi commented Jun 17, 2020