add Index Files section in Pretty URLs recipe

astro.config.mjs

@@ -66,7 +66,10 @@ export default defineConfig({
               label: "Local File Checking with --root-dir",
               link: "/recipes/root-dir",
             },
-            { label: "Pretty URLs", link: "/recipes/pretty-urls" },
+            {
+              label: "Pretty URLs (Fallback Extensions and Index Files)",
+              link: "/recipes/pretty-urls",
+            },
             { label: "Wikilinks", link: "/recipes/wikilinks" },
           ],
         },

src/content/docs/recipes/pretty-urls.md

@@ -1,23 +1,74 @@
 ---
 title: Pretty URLs
+description: >
+  A pretty URL leaves out certain parts of the link to make it shorter and more
+  memorable. Currently, lychee understands two kinds of pretty URLs: links to
+  files which omit the file extension, and links to directories which omit the
+  "/index.html" filename.
 ---
 
-Static site generators such as [Hugo](https://gohugo.io/) can be told to generate
-["pretty" URLs](https://gohugo.io/content-management/urls/#appearance), i.e. URLs
-that do not end in the file extension `.html` but that are still resolving to the
-files with that file extension.
+In the modern web, URLs are often made "pretty" in a number of ways. This makes
+them more concise and memorable, but these links can cause problems for lychee
+when checking local files—pretty links cannot be mapped directly to files
+on disk.
 
-GitHub Pages supports these pretty URLs by default: whether directing the browser
-to https://lychee.cli.rs/index or to https://lychee.cli.rs/index.html, either URL
-will resolve to the same page.
+Currently, lychee understands two kinds of pretty URLs:
+- links to files which omit the file extension, and
+- links to directories which omit the `/index.html` filename.
 
-To help with locally checking links in such scenarios, where the links lack the
-`.html` extension but the files on disk have them, Lychee supports the option
-`--fallback-extensions`:
+For these URLs, lychee has special options to handle them in local files.
+
+:::note[Good to know]
+In lychee, pretty URLs only need special handling in _local_ files. When
+checking links in online webpages, we can rely on the web server to resolve
+pretty links to the right destination. For local files, lychee must
+handle this process itself.
+:::
+
+## Fallback extensions
+
+Static site generators such as Hugo can be told to generate [pretty
+URLs](https://gohugo.io/configuration/ugly-urls/) that omit the `.html` file
+extension. Many hosting services, such as GitHub Pages and GitLab Pages, will
+[automatically resolve][gitlab] these pretty URLs to the underlying `.html` file
+when serving the content.
+
+[gitlab]: https://docs.gitlab.com/user/project/pages/introduction/#resolving-ambiguous-urls
+
+To help with local checking when links lack the `.html` extension but the files
+on disk have them, lychee supports the option `--fallback-extensions`:
 
 ```bash
-# If a local link without a file extension does not resolve to an existing file or
-# directory, let lychee fall back to try again after appending the `.html` or the
-# `.htm` file extension, in that order.
+# If a local link does not resolve to an existing file, lychee will attempt to
+# find a file by appending `.html` or `.htm`, in that order.
 lychee --fallback-extensions html,htm
 ```
+
+## Index files
+[Index files](https://en.wikipedia.org/wiki/Web_server_directory_index) is a
+common web server feature which returns the contents of an "index" file when a
+directory link is requested. This feature is extremely common amongst hosting
+platforms such as GitHub Pages and [GitLab Pages][gitlab], and many websites
+are written to take advantage of it because it avoids needing to write
+`/index.html` at the end of every directory link.
+
+By *default*, lychee does not resolve index files and directory links are considered
+valid as long as the directory exists on disk.
+
+With the `--index-files` option, lychee can be configured to resolve index files:
+```bash
+# If a local link resolves to a directory, lychee will attempt to find one of
+# the listed index files within the directory, in the order given.
+lychee --index-files index.html,index.htm
+```
+If `--index-files` is specified and no file can be found, lychee will consider
+the link to be broken. This can be customized by specifying `.` within the list
+of index file names. The special `.` name will accept the directory if it exists and
+can be used as a fallback after other index file names.
+
+:::tip
+When using `--index-files` together with `--fallback-extensions`, fallback
+extensions are _not_ applied to index file names. The list of file names given
+to `--index-files` should contain any necessary file extensions.
+:::
+