chore: avoid generating subdirectories for each page on new docs site (…

…#15967)

* chore: avoid generating subdirectories for each page on new docs site

Refs #15844

* add comments

* refactor pathPrefix

* update component library permalinks

* rewrite URLs

* fix indentation in package.json

docs/.eleventy.js

@@ -91,6 +91,19 @@ module.exports = function(eleventyConfig) {
         return markdown.render(value);
     });
 
+    /*
+     * Removes `.html` suffix from the given url.
+     * `page.url` will include the `.html` suffix for all documents
+     * except for those written as `index.html` (their `page.url` ends with a `/`).
+     */
+    eleventyConfig.addFilter("prettyURL", url => {
+        if (url.endsWith(".html")) {
+            return url.slice(0, -".html".length);
+        }
+
+        return url;
+    });
+
     //------------------------------------------------------------------------------
     // Plugins
     //------------------------------------------------------------------------------
@@ -345,6 +358,28 @@ module.exports = function(eleventyConfig) {
 
     // END, eleventy-img
 
+    //------------------------------------------------------------------------------
+    // Settings
+    //------------------------------------------------------------------------------
+
+    /*
+     * When we run `eleventy --serve`, Eleventy 1.x uses browser-sync to serve the content.
+     * By default, browser-sync (more precisely, underlying serve-static) will not serve
+     * `foo/bar.html` when we request `foo/bar`. Thus, we need to rewrite URLs to append `.html`
+     * so that pretty links without `.html` can work in a local development environment.
+     *
+     * There's no need to rewrite URLs that end with `/`, because that already works well
+     * (server will return the content of `index.html` in the directory).
+     * URLs with a file extension, like main.css, main.js, sitemap.xml, etc. should not be rewritten
+     */
+    eleventyConfig.setBrowserSyncConfig({
+        middleware: (req, res, next) => {
+            if (!/(?:\.[^/]+|\/)$/u.test(req.url)) {
+                req.url += ".html";
+            }
+            return next();
+        }
+    });
 
     return {
         passthroughFileCopy: true,

docs/package.json

@@ -38,5 +38,8 @@
         "rimraf": "^3.0.2",
         "sass": "^1.52.1",
         "slugify": "^1.6.3"
+    },
+    "engines": {
+        "node": ">=14.0.0"
     }
 }

docs/src/_includes/components/docs-index.html

@@ -1,7 +1,7 @@
 {% set navPages = collections.docs | eleventyNavigation %}
 {% macro renderNavListItem(entry) -%}
 <li class="docs-index__item" {% if entry.children.length %}data-has-children {% endif %}>
-    <a href="{{ entry.url | url }}" {% if entry.url == page.url %} aria-current="true" {% endif %}>{{ entry.title }}</a>
+    <a href="{{ entry.url | url | prettyURL }}" {% if entry.url == page.url %} aria-current="true" {% endif %}>{{ entry.title }}</a>
     {%- if entry.children.length -%}
     <ul data-child-list>
         {%- for child in entry.children %}{{ renderNavListItem(child) }}{% endfor -%}

docs/src/_includes/layouts/base.njk

@@ -9,7 +9,7 @@
     <!-- SEO -->
     <title>{{ title }}</title>
     <meta name="description" content="{{ desc }}">
-    <!--<link rel="canonical" href="https://docs.eslint.org{{ page.url | url }}">-->
+    <!--<link rel="canonical" href="https://docs.eslint.org{{ page.url | url | prettyURL }}">-->
 
     <!-- favicon -->
     <link rel="icon" href="/favicon.ico" sizes="any"><!-- 32×32 -->
@@ -25,7 +25,7 @@
     <meta property="og:image:alt" content="{{ coverAlt }}">
     <meta property="og:locale" content="en_US">
     <meta property="og:type" content="website">
-    <meta property="og:url" content="{{ metadata.url }}{{ page.url }}">
+    <meta property="og:url" content="{{ metadata.url }}{{ page.url | url | prettyURL }}">
     <!-- Twitter -->
     <meta name="twitter:title" content="{{ title }}">
     <meta name="twitter:card" content="summary_large_image">

docs/src/_includes/layouts/components.html

@@ -27,7 +27,7 @@
             <ul class="index__list" id="js-index-list">
                 {% for item in collections.library %}
                 <li class="index__item">
-                    <a href="{{ item.url | url }}" {{ helpers.getLinkActiveState(item.url,
+                    <a href="{{ item.url | url | prettyURL }}" {{ helpers.getLinkActiveState(item.url,
                     page.url) | safe }}>{{ item.data.title }}</a>
                 </li>
                 {% endfor %}

docs/src/library/library.json

@@ -1,4 +1,4 @@
 {
     "layout": "components.html",
-    "permalink": "/component-library/{{ page.fileSlug }}/index.html"
+    "permalink": "/component-library/{{ page.fileSlug }}.html"
 }

docs/src/src.json

@@ -0,0 +1,3 @@
+{
+    "permalink": "{{ page.filePathStem }}.html"
+}

docs/src/static/sitemap.njk

@@ -6,7 +6,7 @@ eleventyExcludeFromCollections: true
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     {% for page in collections.all %}
         <url>
-            <loc>{{ site.url }}{{ page.url | url }}</loc>
+            <loc>{{ site.url }}{{ page.url | url | prettyURL }}</loc>
             <lastmod>{{ page.date.toISOString() }}</lastmod>
             <changefreq>{{ page.data.changeFreq or &quot;monthly&quot; }}</changefreq>
         </url>