[PATCH] docs: set canonical base URL for HTML output

[PATCH] docs: set canonical base URL for HTML output

[Rito Rhymes]

Set the published docs URL as html_baseurl so generated HTML pages
advertise the correct canonical URL metadata.

This helps search engines and other consumers treat docs.kernel.org as
the canonical location for published documentation pages.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
---
 Documentation/conf.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 679861503..f517dfeaf 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -437,6 +437,9 @@ sys.stderr.write("Using %s theme\n" % html_theme)
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["sphinx-static"]
 
+# Canonical base URL for generated HTML pages.
+html_baseurl = "https://docs.kernel.org/"
+
 # If true, Docutils "smart quotes" will be used to convert quotes and dashes
 # to typographically correct entities.  However, conversion of "--" to "—"
 # is not always what we want, so enable only quotes.
-- 
2.51.0

Re: [PATCH] docs: set canonical base URL for HTML output

[Jonathan Corbet]

Rito Rhymes <rito@ritovision.com> writes:

> Set the published docs URL as html_baseurl so generated HTML pages
> advertise the correct canonical URL metadata.
>
> This helps search engines and other consumers treat docs.kernel.org as
> the canonical location for published documentation pages.
>
> Signed-off-by: Rito Rhymes <rito@ritovision.com>
> ---
>  Documentation/conf.py | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 679861503..f517dfeaf 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -437,6 +437,9 @@ sys.stderr.write("Using %s theme\n" % html_theme)
>  # so a file named "default.css" will overwrite the builtin "default.css".
>  html_static_path = ["sphinx-static"]
>  
> +# Canonical base URL for generated HTML pages.
> +html_baseurl = "https://docs.kernel.org/"
> +

What problem does this actually solve; what isn't working as well as it
should due to the lack of this configuration?

...and how does it help all of the people who do their own docs builds?

Thanks,

jon

Re: [PATCH] docs: set canonical base URL for HTML output

[Rito Rhymes]

This is about protecting source authority in indexed search results,
which Linux kernel documentation very much exists in already.

Linux protects its trademarks, uses official marks and domains to
distinguish the project’s identity from copies and forks, and uses
provenance mechanisms such as sigstore for verifying the origin and
authenticity of software artifacts. A canonical URL is a different
angle to cover.

Indexed search results are an important distribution surface for
documentation, and it is also a hostile environment. For a
project like the Linux kernel, where its material is widely
copied, mirrored, archived, rehosted, and referenced across many
alternate paths and contexts, the stakes are higher and
protecting source authority matters more. Given the other ways
Linux already protects project identity, canonical URLs are a
small low-cost measure that supports its source authority for
indexing providers by indicating the preferred official URL for
a given resource.

The documentation site appears agnostic toward search engine
indexing because it neither opts out of indexed search for
compliant crawlers nor explicitly adds directives aimed at
optimizing for it. By being on the open web and not opting out,
it by default participates in the indexed web as a valid and standard
distribution surface for documentation. In that context, if
the site is part of the indexed web whether or not it actively
courts it, then using a low-cost standard signal like a canonical
URL is simply part of managing that reality responsibly.


> ...and how does it help all of the people who do their
> own docs builds?

You accepted the favicon fix earlier but you could argue something
similar about it:

"After someone downloads the Linux repo and runs the documentation
site locally, how does having the little logo visible in the browser
help them? Without it, will they not know they are viewing the Linux
documentation site?"

They are clearly different but what's in common is that they're
low-cost signals supporting the Linux identity on the web.

Rito

Re: [PATCH] docs: set canonical base URL for HTML output

[Jonathan Corbet]

"Rito Rhymes" <rito@ritovision.com> writes:

> The documentation site appears agnostic toward search engine
> indexing because it neither opts out of indexed search for
> compliant crawlers nor explicitly adds directives aimed at
> optimizing for it. By being on the open web and not opting out,
> it by default participates in the indexed web as a valid and standard
> distribution surface for documentation. In that context, if
> the site is part of the indexed web whether or not it actively
> courts it, then using a low-cost standard signal like a canonical
> URL is simply part of managing that reality responsibly.

This sounds like perhaps an argument for lore.kernel.org to set this
variable for its build; I think a reasonable case could be made for
that.  I think that the case for everybody else's build is rather
weaker. 

>
>> ...and how does it help all of the people who do their
>> own docs builds?
>
> You accepted the favicon fix earlier but you could argue something
> similar about it:
>
> "After someone downloads the Linux repo and runs the documentation
> site locally, how does having the little logo visible in the browser
> help them? Without it, will they not know they are viewing the Linux
> documentation site?"

Even a little penguin when viewing a locally generated file seems better
than nothing.  It has little to do with the web itself, and absolutely
nothing to do with one specific web site.

Thanks,

jon

Re: [PATCH] docs: set canonical base URL for HTML output

[Rito Rhymes]

To be clear:

canonical URL + local build = useless

canonical URL set by env var + official published build = source
authority support

hardcoded canonical URL in the source tree + mirror deployments =

1. Benign mirror benefit
    Mirrors inherit a source-authority-supporting default without
    needing to think about it or configure anything themselves.

2. Adversarial / careless mirror mitigation
    Anyone who does not want to preserve that signal must take an
    extra step to remove or override it, adding at least some
    friction to careless or hostile reuse. 

Hardcoding it is simpler, safer and more effective because it makes
preservation of the preferred source the path of least resistance,
requires any departure from it to be explicit, and costs local builds
very little without side effects.

Rito