Add docs for linking in changed pages from MR widgetdocs/direct-link-review-apps

3 files changed, 26 insertions, 8 deletions

diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index 4d740c32fd6..6874583256a 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -416,19 +416,18 @@ and/or `production`) you can see this information in the merge request itself.
 
 ### Go directly from source files to public pages on the environment
 
-> Introduced in GitLab 8.17.
+> Introduced in GitLab 8.17. In GitLab 11.5 the file links
+are surfaced to the merge request widget.
 
-To go one step further, we can specify a Route Map to get GitLab to show us "View on [environment URL]" buttons to go directly from a file to that file's representation on the deployed website. It will be exposed in a few places:
-
-| In the diff for a merge request, comparison or commit | In the file view |
-| ------ | ------ |
-| !["View on env" button in merge request diff](img/view_on_env_mr.png) | !["View on env" button in file view](img/view_on_env_blob.png) |
+You can specify a Route Map to get GitLab to show "View on <environment URL>"
+buttons to go directly from a file to that file's representation on the
+[deployed website via Review Apps](review_apps/index.md).
 
 To get this to work, you need to tell GitLab how the paths of files in your repository map to paths of pages on your website, using a Route Map.
 
 A Route Map is a file inside the repository at `.gitlab/route-map.yml`, which contains a YAML array that maps `source` paths (in the repository) to `public` paths (on the website).
-
-This is an example of a route map for [Middleman](https://middlemanapp.com) static websites like [http://about.gitlab.com](https://gitlab.com/gitlab-com/www-gitlab-com):
+Below is an example of a route map for [Middleman](https://middlemanapp.com) static websites
+like <https://gitlab.com/gitlab-com/www-gitlab-com>:
 
 ```yaml
 # Team data
@@ -467,6 +466,25 @@ In the example above, the fact that mappings are evaluated in order of their def
 
 ---
 
+Once you have the route mapping set up, it will be exposed in a few places:
+
+- In the merge request widget. The **View app** button will take you to the
+  environment URL you have set up in `.gitlab-ci.yml`. The dropdown will render
+  the first 5 matched items from the route map, but you can filter them if more
+  than 5 are available.
+
+    ![View app file list in merge request widget](img/view_on_mr_widget.png)
+
+- In the diff for a merge request, comparison, or commit.
+
+    !["View on env" button in merge request diff](img/view_on_env_mr.png)
+
+- In the blob file view.
+
+    !["View on env" button in file view](img/view_on_env_blob.png) |
+
+---
+
 We now have a full development cycle, where our app is tested, built, deployed
 as a Review app, deployed to a staging server once the merge request is merged,
 and finally manually deployed to the production server. What we just described
diff --git a/doc/ci/img/view_on_env_blob.png b/doc/ci/img/view_on_env_blob.png
index dd9ca40280a..acc457fbb38 100644
--- a/doc/ci/img/view_on_env_blob.png
+++ b/doc/ci/img/view_on_env_blob.png
diff --git a/doc/ci/img/view_on_mr_widget.png b/doc/ci/img/view_on_mr_widget.png
new file mode 100644
index 00000000000..04f4b58df62
--- /dev/null
+++ b/doc/ci/img/view_on_mr_widget.png