Merge branch 'update-pages-extensionless-urls' into 'master'

Add support for extensionless pages URLs

See merge request gitlab-org/gitlab-ce!24876

1 files changed, 51 insertions, 0 deletions

diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md
index 2bb6fcd9d74..cebff38ba88 100644
--- a/doc/user/project/pages/introduction.md
+++ b/doc/user/project/pages/introduction.md
@@ -356,6 +356,57 @@ By pre-compressing the files and including both versions in the artifact, Pages
 can serve requests for both compressed and uncompressed content without
 needing to compress files on-demand.
 
+### Resolving ambiguous URLs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/issues/95) in GitLab 11.8
+
+GitLab Pages makes assumptions about which files to serve when receiving a
+request for a URL that does not include an extension.
+
+Consider a Pages site deployed with the following files:
+
+```
+public/
+├─┬ index.html
+│ ├ data.html
+│ └ info.html
+│
+├── data/
+│   └── index.html
+├── info/
+│   └── details.html
+└── other/
+    └── index.html
+```
+
+Pages supports reaching each of these files through several different URLs. In
+particular, it will always look for an `index.html` file if the URL only
+specifies the directory. If the URL references a file that doesn't exist, but
+adding `.html` to the URL leads to a file that *does* exist, it will be served
+instead. Here are some examples of what will happen given the above Pages site:
+
+| URL path             | HTTP response | File served |
+| -------------------- | ------------- | ----------- |
+| `/`                  | `200 OK`      | `public/index.html` |
+| `/index.html`        | `200 OK`      | `public/index.html` |
+| `/index`             | `200 OK`      | `public/index.html` |
+| `/data`              | `200 OK`      | `public/data/index.html` |
+| `/data/`             | `200 OK`      | `public/data/index.html` |
+| `/data.html`         | `200 OK`      | `public/data.html` |
+| `/info`              | `200 OK`      | `public/info.html` |
+| `/info/`             | `200 OK`      | `public/info.html` |
+| `/info.html`         | `200 OK`      | `public/info.html` |
+| `/info/details`      | `200 OK`      | `public/info/details.html` |
+| `/info/details.html` | `200 OK`      | `public/info/details.html` |
+| `/other`             | `302 Found`   | `public/other/index.html` |
+| `/other/`            | `200 OK`      | `public/other/index.html` |
+| `/other/index`       | `200 OK`      | `public/other/index.html` |
+| `/other/index.html`  | `200 OK`      | `public/other/index.html` |
+
+NOTE: **Note:**
+When `public/data/index.html` exists, it takes priority over the `public/data.html`
+file for both the `/data` and `/data/` URL paths.
+
 ### Add a custom domain to your Pages website
 
 For a complete guide on Pages domains, read through the article