diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md
index e86726524d068b628da4db45c494df35d38a46d1..459a4dcc6a388cca93c4c91981a74a601342e2ea 100644
--- a/doc/administration/pages/index.md
+++ b/doc/administration/pages/index.md
@@ -590,6 +590,27 @@ gitlab_pages['redirects_max_path_segments'] = 50
 gitlab_pages['redirects_max_rule_count'] = 2000
 ```
 
+## Use environment variables
+
+You can pass an environment variable to the Pages deamon, for example
+to enable a feature flag.
+
+For example, to enable the configurable directory feature:
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_pages['env'] = {
+     'FF_CONFIGURABLE_ROOT_DIR' => "true"
+   }
+   ```
+
+1. Save the file and reconfigure GitLab:
+
+   ```shell
+   sudo gitlab-ctl reconfigure
+   ```
+
 ## Activate verbose logging for daemon
 
 Follow the steps below to configure verbose logging of GitLab Pages daemon.
diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md
index 73bfe018a7d3a8cfd2014cdb1388f47548816bb2..1aef5bd304019f2a08116a6ede3fdaf9d5a7a7bc 100644
--- a/doc/user/project/pages/introduction.md
+++ b/doc/user/project/pages/introduction.md
@@ -23,8 +23,6 @@ In brief, this is what you need to upload your website in GitLab Pages:
 1. Domain of the instance: domain name that is used for GitLab Pages
    (ask your administrator).
 1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`](../../../ci/yaml/index.md#pages) in the root directory of your repository.
-1. A directory called `public` in your site's repository containing the content
-   to be published.
 1. GitLab Runner enabled for the project.
 
 ## GitLab Pages on GitLab.com
@@ -278,6 +276,39 @@ instead. Here are some examples of what happens given the above Pages site:
 When `public/data/index.html` exists, it takes priority over the `public/data.html` file
 for both the `/data` and `/data/` URL paths.
 
+## Customize the default folder
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/859) in GitLab 16.1 with a Pages flag named `FF_CONFIGURABLE_ROOT_DIR`. Disabled by default.
+> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1073) in GitLab 16.1.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available,
+ask an administrator to [enable the Pages feature flag](../../../administration/pages/index.md#use-environment-variables)
+`FF_CONFIGURABLE_ROOT_DIR="true"`. On GitLab.com, this feature is available.
+
+By default, the [artifact](../../../ci/jobs/job_artifacts.md) folder
+that contains the static files of your site needs to have the name `public`.
+
+To change that folder name to any other value, add a `publish` property to your
+`pages` job configuration in `.gitlab-ci.yml`.
+
+The following example publishes a folder named `dist` instead:
+
+```yaml
+pages:
+  script:
+    - npm run build
+  artifacts:
+    paths:
+      - dist
+  publish: dist
+```
+
+If you're using a folder name other than `public`you must specify
+the directory to be deployed with Pages both as an artifact, and under the
+`publish` property. The reason you need both is that you can define multiple paths
+as artifacts, and GitLab doesn't know which one you want to deploy.
+
 ## Known issues
 
 For a list of known issues, see the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages).
diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md
index 6ee8ea17aee1068b1f4d5f80f5b689b7709c9099..68023b87560c474c39dec05a70cc6b922f3d2009 100644
--- a/doc/user/project/pages/public_folder.md
+++ b/doc/user/project/pages/public_folder.md
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # GitLab Pages public folder **(FREE)**
 
-All the files that should be accessible by the browser must be in a root-level folder called `public`.
+> With GitLab 16.1 we introduced the ability to configure the published folder in `.gitlab-ci.yml`, so you longer need to change your framework config. For more information, see how to [set a custom folder to be deployed with Pages](introduction.md#customize-the-default-folder).
 
 Follow these instructions to configure the `public` folder
 for the following frameworks.