docs: Switch to version-relative URLs (#15978)

nzakas · mdjermanovic · web-flow · commit df7768e16a5a · 2022-06-11T02:56:54.000+02:00
* docs: Switch to version-relative URLs

Implements /docs/head and /docs/latest as ways to load the docs from
the HEAD branch and from the latest release.

* Update Makefile.js

* Update docs/src/_includes/components/nav-version-switcher.html

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;

* Update docs/src/_includes/components/version-switcher.html

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;

* Update docs/src/_includes/partials/versions-list.html

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;
diff --git a/Makefile.js b/Makefile.js
@@ -318,6 +318,10 @@ function generatePrerelease(prereleaseId) {
  */
 function publishRelease() {
     ReleaseOps.publishRelease();
+
+    // push to latest branch to trigger docs deploy
+    exec("git push origin HEAD:latest -f");
+
     publishSite();
 }
 
diff --git a/docs/.eleventy.js b/docs/.eleventy.js
@@ -16,13 +16,29 @@ const {
 module.exports = function(eleventyConfig) {
 
     /*
-     * The site is loaded from /docs on eslint.org and so we need to adjust
-     * the path prefix so URLs are evaluated correctly.
+     * The docs stored in the eslint repo are loaded through eslint.org at
+     * at /docs/head to show the most recent version of the documentation
+     * based on the HEAD commit. This gives users a preview of what's coming
+     * in the next release. This is the way that the site works locally so
+     * it's easier to see if URLs are broken.
+     *
+     * When a release is published, HEAD is pushed to the "latest" branch.
+     * Netlify deploys that branch as well, and in that case, we want the
+     * docs to be loaded from /docs/latest on eslint.org.
      *
      * The path prefix is turned off for deploy previews so we can properly
      * see changes before deployed.
      */
-    const pathPrefix = process.env.CONTEXT === "deploy-preview" ? "" : "/docs";
+
+    let pathPrefix = "/docs/head";
+
+    if (process.env.CONTEXT === "deploy-preview") {
+        pathPrefix = "";
+    } else if (process.env.BRANCH === "latest") {
+        pathPrefix = "/docs/latest";
+    }
+
+    eleventyConfig.addGlobalData("GIT_BRANCH", process.env.BRANCH);
 
     //------------------------------------------------------------------------------
     // Filters
diff --git a/docs/src/_includes/components/nav-version-switcher.html b/docs/src/_includes/components/nav-version-switcher.html
@@ -12,7 +12,8 @@
             <span class="label__text">Version</span>
         </label>
         <select name="version selector" id="nav-version-select" aria-describedby="nav-version-infobox" class="c-custom-select switcher__select auto-switcher">
-            <option value="{{ eslintVersion }}" selected>v{{ eslintVersion }}</option>
+            <option value="HEAD" data-url="/docs/head/" {% if GIT_BRANCH !="latest" %}selected{% endif %}>HEAD</option>
+            <option value="{{ eslintVersion }}" data-url="/docs/latest/" {% if GIT_BRANCH=="latest" %}selected{% endif %}>v{{ eslintVersion }}</option>
             {% for version in versions.items %}
             <option value="{{ version.number }}"
                     data-url="{{ version.url }}">
diff --git a/docs/src/_includes/components/version-switcher.html b/docs/src/_includes/components/version-switcher.html
@@ -12,7 +12,8 @@
             <span class="label__text">Version</span>
         </label>
         <select name="version selector" id="version-select" aria-describedby="version-infobox" class="c-custom-select switcher__select auto-switcher">
-            <option value="{{ eslintVersion }}" selected>v{{ eslintVersion }}</option>
+            <option value="HEAD" data-url="/docs/head/"  {% if GIT_BRANCH != "latest" %}selected{% endif %}>HEAD</option>
+            <option value="{{ eslintVersion }}" data-url="/docs/latest/"  {% if GIT_BRANCH == "latest" %}selected{% endif %}>v{{ eslintVersion }}</option>
             {% for version in versions.items %}
             <option value="{{ version.number }}"
                     data-url="{{ version.url }}">
diff --git a/docs/src/_includes/partials/versions-list.html b/docs/src/_includes/partials/versions-list.html
@@ -1,5 +1,7 @@
 <ul class="versions-list">
+    <li><a href="/docs/head/" {% if GIT_BRANCH != "latest" %} data-current="true" {% endif %}>HEAD</a></li>
+    <li><a href="/docs/latest/" {% if GIT_BRANCH == "latest" %} data-current="true" {% endif %}>v{{ eslintVersion }}</a></li>
     {%- for version in versions.items -%}
-    <li><a href="{{ version.url }}" {% if config.version == version.number %} data-current="true" {% endif %}>v{{ version.number }}</a></li>
+    <li><a href="{{ version.url }}">v{{ version.number }}</a></li>
     {%- endfor -%}
 </ul>
