docs: deploy prerelease docs under the /docs/next/ path (#16541)

* docs: deploy prerelease docs under the `/next` path

* docs: deploy prerelease docs under the /docs/next/ path

* docs: fix versions list

* docs: fix versions page

* fix: update docs/.eleventy.js

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

* docs: update docs/.eleventy.js

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

* docs: fix lint

* docs: show NEXT based on config

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

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>
Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

Makefile.js

@@ -345,9 +345,18 @@ function generatePrerelease(prereleaseId) {
  */
 function publishRelease() {
     ReleaseOps.publishRelease();
+    const releaseInfo = JSON.parse(cat(".eslint-release-info.json"));
+    const isPreRelease = /[a-z]/u.test(releaseInfo.version);
 
-    // push to latest branch to trigger docs deploy
-    exec("git push origin HEAD:latest -f");
+    /*
+     * for a pre-release, push to the "next" branch to trigger docs deploy
+     * for a release, push to the "latest" branch to trigger docs deploy
+     */
+    if (isPreRelease) {
+        exec("git push origin HEAD:next -f");
+    } else {
+        exec("git push origin HEAD:latest -f");
+    }
 
     publishSite();
 }

docs/.eleventy.js

@@ -25,8 +25,9 @@ module.exports = function(eleventyConfig) {
      * 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.
+     * When a pre-release is published, HEAD is pushed to the "next" branch.
+     * Netlify deploys those branches as well, and in that case, we want the
+     * docs to be loaded from /docs/latest or /docs/next on eslint.org.
      *
      * The path prefix is turned off for deploy previews so we can properly
      * see changes before deployed.
@@ -38,6 +39,8 @@ module.exports = function(eleventyConfig) {
         pathPrefix = "/";
     } else if (process.env.BRANCH === "latest") {
         pathPrefix = "/docs/latest/";
+    } else if (process.env.BRANCH === "next") {
+        pathPrefix = "/docs/next/";
     }
 
     //------------------------------------------------------------------------------
@@ -49,6 +52,7 @@ module.exports = function(eleventyConfig) {
 
     eleventyConfig.addGlobalData("site_name", siteName);
     eleventyConfig.addGlobalData("GIT_BRANCH", process.env.BRANCH);
+    eleventyConfig.addGlobalData("HEAD", process.env.BRANCH === "main");
     eleventyConfig.addGlobalData("NOINDEX", process.env.BRANCH !== "latest");
     eleventyConfig.addDataExtension("yml", contents => yaml.load(contents));
 

docs/src/_data/config.json

@@ -1,4 +1,5 @@
 {
     "lang": "en",
-    "version": "7.26.0"
+    "version": "7.26.0",
+    "showNextVersion": false
 }

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

@@ -12,8 +12,11 @@
             <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="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>
+            <option value="HEAD" data-url="/docs/head/" {% if HEAD %}selected{% endif %}>HEAD</option>
+            {% if config.showNextVersion == true %}
+                <option value="NEXT" data-url="/docs/next/" {% if GIT_BRANCH == "next" %}selected{% endif %}>NEXT</option>
+            {% endif %}
+            <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,10 @@
             <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="HEAD" data-url="/docs/head/"  {% if GIT_BRANCH != "latest" %}selected{% endif %}>HEAD</option>
+            <option value="HEAD" data-url="/docs/head/"  {% if HEAD %}selected{% endif %}>HEAD</option>
+            {% if config.showNextVersion == true %}
+              <option value="NEXT" data-url="/docs/next/" {% if GIT_BRANCH=="next" %}selected{% endif %}>NEXT</option>
+            {% endif %}
             <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 }}"

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

@@ -1,5 +1,8 @@
 <ul class="versions-list">
-    <li><a href="/docs/head/" {% if GIT_BRANCH != "latest" %} data-current="true" {% endif %}>HEAD</a></li>
+    <li><a href="/docs/head/" {% if HEAD %} data-current="true" {% endif %}>HEAD</a></li>
+    {% if config.showNextVersion == true %}
+      <li><a href="/docs/next/" {% if GIT_BRANCH == "next" %} data-current="true" {% endif %}>NEXT</a></li>
+    {% endif %}
     <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 }}">v{{ version.number }}</a></li>