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

[mdjermanovic]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[ ] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[x] Other, please explain:

Refs #15844

In the current site (eslint/website repo), Eleventy writes from foo/bar.md to foo/bar.html, which makes path foo/bar in the URL.

In the new docs site, Eleventy writes from foo/bar.md to foo/bar/index.html (this is default behavior), which makes path foo/bar/ in the URL.

The added trailing slash breaks document-relative links.

This PR fixes the new docs site to generate files in the same way as the current site.

What changes did you make? (Give an overview)

• Added src/src.json that overrides default permalinks. This is the same as docs/docs.json on the current site. Per the data cascade, this shouldn't affect templates that have a permalink in the front matter (like the sitemap, robots, etc.), which is good.
• With this change, page.url includes the .html suffix, so I added prettyURL filter that removes .html, and used the filter in places where we're generating urls from page.url. Namely: docs index, sitemap, canonical links, and og:url.
• With the above changes, links didn't work locally (http://localhost:2023), because browser-sync doesn't serve foo.html by default when foo is requested, so I had to add "html" extension in the browser-sync config through eleventy. Unfortunately, eleventy shallow merges the added config, so this change overwrites all eleventy's browser-sync server settings, including settings related to pathPrefix, resulting in a totally broken site. As those settings look fairly complex, instead of trying to replicate them I decided to remove pathPrefix when the site is generated by npm start.
• I also updated components library links. Is that okay?

Is there anything you'd like reviewers to focus on?

Check that the links work well in the deployment preview, and that there are no trailing slash redirections.

[netlify]

✅ Deploy Preview for docs-eslint ready!

Name	Link
🔨 Latest commit	8f6793a
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/62a38105972497000831bb56
😎 Deploy Preview	https://deploy-preview-15967--docs-eslint.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[nzakas]

Thanks for taking a look at this. This approach feels error-prone to me. If we didn’t need a special filter on the current website, that seems to indicate that there should be a way to do the same thing without a special filter that we need to remember to use in different places.

[nzakas]

I’m concerned about this approach. I don’t think it’s at all clear where we should and should not be using this filter, and I fear this will cause more errors in the future.

[mdjermanovic]

The rule would be to use this filter in all places where page.url is written into the output content. In places where it is used in calculations, there is no need to use the filter (example on the current website). This is the same approach as on the current website.

If you have an idea for another approach, I could try it. We could maybe write the files without .html extension, but that would probably require additional configuration on Netlify to treat extensionless files as html.

[mdjermanovic]

If we didn’t need a special filter on the current website, that seems to indicate that there should be a way to do the same thing without a special filter that we need to remember to use in different places.

We are removing .html suffix in different places on the current website too: og:url, twitter:url, canonical url, blog post links, feed links. This is the same thing we do on the current website, I just extracted removing .html into a filter so that we don't have to repeat replace: '.html', ''.

[nzakas]

I think we can actually solve this in a simpler way. Explained in #15844 (comment).

[nzakas]

We should use the pathPrefix locally too, otherwise, we won't be able to tell when the url filter isn't used. The way I set it up was so that these errors would be obvious locally because we won't get them in deploy preview.

[mdjermanovic]

I couldn't make it work (see the third point in "What changes did you make" in the original post). I'll see if the browser-sync config override can be done differently.

[nzakas]

Huh. I haven’t had any trouble since I first added pathPrefix. Eleventy generates an index.html file at the root that redirects to /docs and then everything works perfectly for me. I’m using the same setup on the playground.

[mdjermanovic]

Eleventy's built-in server returns the content of foo/index.html when we request foo/, but it doesn't return the content of foo/bar.html when we request foo/bar, which is what we'll have after this change. It needs some additional configuration.

Without pathPrefix, it works well when I add serveStaticOptions: { extensions: [ 'html' ] } to the config that eleventy passes into the underlying server.

eleventyConfig.setBrowserSyncConfig({
    server: {
        baseDir: "_site",
        serveStaticOptions: {
            extensions: ["html"]
        }
    }
});

With pathPrefix, for some reason it doesn't work.

eleventyConfig.setBrowserSyncConfig({
    server: {
        baseDir: "_site/_eleventy_redirect",
        routes: {
            "/docs": "_site"
        },
        serveStaticOptions: {
            extensions: ["html"]
        }
    }
});

Cannot GET /docs/user-guide/configuring/configuration-files

[mdjermanovic]

I tried with rewriting URLs instead of configuring the server. That seems to work well so I restored pathPrefix for local development.

[nzakas]

As mentioned earlier, let's leave this as-is.

[nzakas]

LGTM. I verified this is working for me locally.