Merge branch 'eread/refine-documentation-url-ui-and-docs' into 'master'

Refine Documentation pages URL UI and documentation

See merge request gitlab-org/gitlab!67293

app/views/admin/application_settings/_help_page.html.haml

@@ -7,20 +7,22 @@
     .form-group
       = f.label :help_page_text, _('Additional text to show on the Help page'), class: 'label-bold'
       = f.text_area :help_page_text, class: 'form-control gl-form-input', rows: 4
-      .form-text.text-muted= _('Markdown enabled')
+      .form-text.text-muted= _('Markdown enabled.')
     .form-group
       .form-check
         = f.check_box :help_page_hide_commercial_content, class: 'form-check-input'
         = f.label :help_page_hide_commercial_content, class: 'form-check-label' do
-          = _('Hide marketing-related entries from the Help page.')
+          = _('Hide marketing-related entries from the Help page')
     .form-group
       = f.label :help_page_support_url, _('Support page URL'), class: 'label-bold'
-      = f.text_field :help_page_support_url, class: 'form-control gl-form-input', placeholder: 'http://company.example.com/getting-help', :'aria-describedby' => 'support_help_block'
-      %span.form-text.text-muted#support_help_block= _('Alternate support URL for Help page and Help dropdown')
+      = f.text_field :help_page_support_url, class: 'form-control gl-form-input', placeholder: 'https://company.example.com/getting-help', :'aria-describedby' => 'support_help_block'
+      %span.form-text.text-muted#support_help_block= _('Alternate support URL for Help page and Help dropdown.')
 
     - if show_documentation_base_url_field?
       .form-group
         = f.label :help_page_documentation_base_url, _('Documentation pages URL'), class: 'label-bold'
         = f.text_field :help_page_documentation_base_url, class: 'form-control gl-form-input', placeholder: 'https://docs.gitlab.com'
-
+        - docs_link_url = help_page_path('user/admin_area/settings/help_page', anchor: 'destination-requirements')
+        - docs_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: docs_link_url }
+        %span.form-text.text-muted#support_help_block= html_escape(_('Requests for pages at %{code_start}%{help_text_url}%{code_end} redirect to the URL. The destination must meet certain requirements. %{docs_link_start}Learn more.%{docs_link_end}')) % { code_start: '<code>'.html_safe, help_text_url: help_url, code_end: '</code>'.html_safe, docs_link_start: docs_link_start, docs_link_end: '</a>'.html_safe }
   = f.submit _('Save changes'), class: "gl-button btn btn-confirm"

doc/user/admin_area/settings/help_page.md

@@ -66,18 +66,24 @@ You can specify a custom URL to which users are directed when they:
 1. In the **Support page URL** field, enter the URL.
 1. Select **Save changes**.
 
-## Redirect GitLab documentation links
+## Redirect `/help` pages
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43157) in GitLab 13.5.
-> - Enabled on GitLab.com and is ready for production use. Available to GitLab.com administrators only.
+> - Enabled on GitLab.com and is ready for production use.
 
 NOTE:
 On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to
 [enable the `:help_page_documentation_redirect` flag](../../../administration/feature_flags.md).
 On GitLab.com, this feature is available but can be configured by GitLab.com administrators only.
 
-Documentation links go to the `/help` section on the instance by default, but you can
-redirect these links to an external documentation site like `https://docs.gitlab.com`:
+The `/help` URL of a GitLab instance displays a basic version of the documentation sourced from the
+[`doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) of GitLab. `/help` links
+are often used for contextual help.
+
+You can redirect these `/help` links to either:
+
+- The more navigable and searchable version published at [`docs.gitlab.com`](https://docs.gitlab.com).
+- A destination that meets [necessary requirements](#destination-requirements).
 
 1. On the top bar, select **Menu >** **{admin}** **Admin**.
 1. In the left sidebar, select **Settings > Preferences**.
@@ -85,6 +91,18 @@ redirect these links to an external documentation site like `https://docs.gitlab
 1. In the **Documentation pages URL** field, enter the URL.
 1. Select **Save changes**.
 
+### Destination requirements
+
+When redirecting `/help`, GitLab:
+
+- Redirects requests to the specified URL.
+- Appends `ee`  and the documentation path to the URL.
+- Appends `.html` to the URL, and removes `.md` if necessary.
+
+For example, if the URL is set to `https://docs.gitlab.com`, requests for
+`/help/user/admin_area/settings/help_page.md` redirect to:
+`https://docs.gitlab.com/ee/user/admin_area/settings/help_page.html`.
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues

ee/app/views/admin/application_settings/_help_text_setting.haml

@@ -3,4 +3,4 @@
 .form-group
   = form.label :help_text, _('Additional text to show on the sign-in page'), class: 'label-bold'
   = form.text_area :help_text, class: 'form-control gl-form-input', rows: 4
-  .form-text.text-muted= _('Markdown enabled')
+  .form-text.text-muted= _('Markdown enabled.')

locale/gitlab.pot

@@ -3420,7 +3420,7 @@ msgstr ""
 msgid "Also unassign this user from related issues and merge requests"
 msgstr ""
 
-msgid "Alternate support URL for Help page and Help dropdown"
+msgid "Alternate support URL for Help page and Help dropdown."
 msgstr ""
 
 msgid "Alternatively, you can convert your account to a managed account by the %{group_name} group."
@@ -16363,7 +16363,7 @@ msgstr ""
 msgid "Hide list"
 msgstr ""
 
-msgid "Hide marketing-related entries from the Help page."
+msgid "Hide marketing-related entries from the Help page"
 msgstr ""
 
 msgid "Hide payload"
@@ -20211,7 +20211,7 @@ msgstr ""
 msgid "Markdown Help"
 msgstr ""
 
-msgid "Markdown enabled"
+msgid "Markdown enabled."
 msgstr ""
 
 msgid "Markdown is supported"
@@ -28080,6 +28080,9 @@ msgstr ""
 msgid "Requests Profiles"
 msgstr ""
 
+msgid "Requests for pages at %{code_start}%{help_text_url}%{code_end} redirect to the URL. The destination must meet certain requirements. %{docs_link_start}Learn more.%{docs_link_end}"
+msgstr ""
+
 msgid "Requests per period"
 msgstr ""
 

spec/features/admin/admin_settings_spec.rb

@@ -585,7 +585,7 @@ RSpec.describe 'Admin updates settings' do
 
         page.within('.as-help-page') do
           fill_in 'Additional text to show on the Help page', with: 'Example text'
-          check 'Hide marketing-related entries from the Help page.'
+          check 'Hide marketing-related entries from the Help page'
           fill_in 'Support page URL', with: new_support_url
           fill_in 'Documentation pages URL', with: new_documentation_url
           click_button 'Save changes'