docs: Switch to version-relative URLs

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();
 }
 

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

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 }}">

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 }}">

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>