From 44c7cc6971d8811f50e312f4e9560284676a66c1 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Dec 2022 12:13:57 +0100 Subject: [PATCH 1/5] Experiment adding a dynamic canonical URL to mkdocs --- .readthedocs.yaml | 11 +++++++++++ mkdocs.yml | 1 + 2 files changed, 12 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d9222bb..c5e81a3 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,8 +11,19 @@ version: 2 # tools: # python: "3.10" +# This pattern will be supported by a better environment variable, proposed +# here: TBD +build: + os: ubuntu-22.04 + tools: + python: "3.10" + jobs: + pre_build: + - export "MKDOCS_SITE_URL=$READTHEDOCS_PROJECT" + mkdocs: configuration: mkdocs.yml + fail_on_warning: true # Optionally declare the Python requirements required to build your docs python: diff --git a/mkdocs.yml b/mkdocs.yml index 2a5a12e..0e94b62 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,5 @@ site_name: Basic MkDocs Example Project +site_url: !ENV MKDOCS_SITE_URL theme: name: readthedocs highlightjs: true From b36ff3e97208fa703b120e3a2cb6f3ab539f79e4 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Dec 2022 13:17:28 +0100 Subject: [PATCH 2/5] Adds an example pattern for canonical URLs. --- .readthedocs.yaml | 10 ---------- mkdocs.yml | 6 +++++- 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index c5e81a3..948cbaa 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,16 +11,6 @@ version: 2 # tools: # python: "3.10" -# This pattern will be supported by a better environment variable, proposed -# here: TBD -build: - os: ubuntu-22.04 - tools: - python: "3.10" - jobs: - pre_build: - - export "MKDOCS_SITE_URL=$READTHEDOCS_PROJECT" - mkdocs: configuration: mkdocs.yml fail_on_warning: true diff --git a/mkdocs.yml b/mkdocs.yml index 0e94b62..a9e0d56 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,9 @@ site_name: Basic MkDocs Example Project -site_url: !ENV MKDOCS_SITE_URL +# Until https://github.com/readthedocs/readthedocs.org/issues/9781 is fixed, you need to +# define CUSTOM_CANONICAL_URL yourself as a workaround. +# (don't expose it to PRs, they build on different URLs) +# For instance, define it as https://SLUG.readthedocs.io/en/stable/ +site_url: !ENV [READTHEDOCS_CANONICAL_URL, CUSTOM_CANONICAL_URL, ""] theme: name: readthedocs highlightjs: true From f13b5db713314e4a7bc13fcdc57b5e8273f4af2c Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Dec 2022 13:30:32 +0100 Subject: [PATCH 3/5] Add better comment for mkdocs.yml --- mkdocs.yml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index a9e0d56..276ecd5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,9 +1,17 @@ site_name: Basic MkDocs Example Project -# Until https://github.com/readthedocs/readthedocs.org/issues/9781 is fixed, you need to -# define CUSTOM_CANONICAL_URL yourself as a workaround. -# (don't expose it to PRs, they build on different URLs) -# For instance, define it as https://SLUG.readthedocs.io/en/stable/ + +# This setting is required for Canonical URLs. +# You can read more about why you should consider using this: +# https://docs.readthedocs.io/en/stable/canonical-urls.html +# +# Until https://github.com/readthedocs/readthedocs.org/issues/9781 is fixed, +# you need to define CUSTOM_CANONICAL_URL yourself as a workaround. +# +# For instance, navigate to Admin => Environment and define +# CUSTOM_CANONICAL_URL=https://SLUG.readthedocs.io/en/stable/ +# (don't expose it to PRs, they publish on different URLs) site_url: !ENV [READTHEDOCS_CANONICAL_URL, CUSTOM_CANONICAL_URL, ""] + theme: name: readthedocs highlightjs: true From 14037eb27811873c97894343b4d333bc1ed27661 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Dec 2022 13:42:30 +0100 Subject: [PATCH 4/5] Test quoting what is lost to SafeLoader --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 276ecd5..cc42825 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,7 +10,7 @@ site_name: Basic MkDocs Example Project # For instance, navigate to Admin => Environment and define # CUSTOM_CANONICAL_URL=https://SLUG.readthedocs.io/en/stable/ # (don't expose it to PRs, they publish on different URLs) -site_url: !ENV [READTHEDOCS_CANONICAL_URL, CUSTOM_CANONICAL_URL, ""] +site_url: "!ENV [READTHEDOCS_CANONICAL_URL, CUSTOM_CANONICAL_URL, '']" theme: name: readthedocs From 5f209f0ebcab2c2dedf289ac10aa385b0f37916b Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 7 Dec 2022 13:49:33 +0100 Subject: [PATCH 5/5] Try a simpler pattern? --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index cc42825..7c80e9c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,7 +10,7 @@ site_name: Basic MkDocs Example Project # For instance, navigate to Admin => Environment and define # CUSTOM_CANONICAL_URL=https://SLUG.readthedocs.io/en/stable/ # (don't expose it to PRs, they publish on different URLs) -site_url: "!ENV [READTHEDOCS_CANONICAL_URL, CUSTOM_CANONICAL_URL, '']" +site_url: !ENV CUSTOM_CANONICAL_URL theme: name: readthedocs