Documenter.jl: A customizable footer on generated pages

Created on 18 Nov 2019 · 7Comments · Source: JuliaDocs/Documenter.jl

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.

HTML Enhancement help wanted

Source

MikeInnes

👍1

Most helpful comment

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 on 17 Jun 2020

👍4

All 7 comments

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

Happy to oblige :smile:

The <head> tag is created in render_head. Would just have to add the necessary <meta>s there.
https://github.com/JuliaDocs/Documenter.jl/blob/40c0f5335ada263157c5305bd85ca695a0896509/src/Writers/HTMLWriter.jl#L731-L779

And it would be perfectly fine to add any additional keywords to HTML too, so that users could define their own additional metadata:
https://github.com/JuliaDocs/Documenter.jl/blob/40c0f5335ada263157c5305bd85ca695a0896509/src/Writers/HTMLWriter.jl#L316-L364

mortenpi on 18 Nov 2019

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?

MikeInnes on 18 Nov 2019

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.

mortenpi on 18 Nov 2019

👍1

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.

MikeInnes on 18 Nov 2019

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.

ChrisRackauckas on 22 Nov 2019

👎2

Just putting these here:

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

KristofferC on 2 Dec 2019

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.: