Merge branch 'help-page-helper' into 'master'

Add helpPagePath helper function

See merge request gitlab-org/gitlab!48106

app/assets/javascripts/design_management/components/design_notes/design_reply_form.vue

@@ -2,6 +2,7 @@
 import { GlButton, GlModal } from '@gitlab/ui';
 import MarkdownField from '~/vue_shared/components/markdown/field.vue';
 import { s__ } from '~/locale';
+import { helpPagePath } from '~/helpers/help_page_helper';
 
 export default {
   name: 'DesignReplyForm',
@@ -60,6 +61,9 @@ export default {
         ? s__('DesignManagement|Comment')
         : s__('DesignManagement|Save comment');
     },
+    markdownDocsPath() {
+      return helpPagePath('user/markdown');
+    },
   },
   mounted() {
     this.focusInput();
@@ -89,7 +93,7 @@ export default {
       :can-attach-file="false"
       :enable-autocomplete="true"
       :textarea-value="value"
-      markdown-docs-path="/help/user/markdown"
+      :markdown-docs-path="markdownDocsPath"
       class="bordered-box"
     >
       <template #textarea>

app/assets/javascripts/helpers/help_page_helper.js

+import { joinPaths, setUrlFragment } from '~/lib/utils/url_utility';
+
+const HELP_PAGE_URL_ROOT = '/help/';
+
+/**
+ * Generate link to a GitLab documentation page.
+ *
+ * This is designed to mirror the Ruby `help_page_path` helper function, so that
+ * the two can be used interchangeably.
+ * @param {String} path           - Path to doc file relative to the doc/ directory in the GitLab repository.
+ *                                  Optionally, including `.md` or `.html` prefix
+ * @param {String} options.anchor - Name of the anchor to scroll to on the documentation page.
+ */
+export const helpPagePath = (path, { anchor = '' } = {}) => {
+  let helpPath = joinPaths(gon.relative_url_root || '/', HELP_PAGE_URL_ROOT, path);
+  if (anchor) {
+    helpPath = setUrlFragment(helpPath, anchor);
+  }
+
+  return helpPath;
+};

doc/development/documentation/index.md

@@ -369,6 +369,19 @@ You can combine one or more of the following:
      = link_to 'Help page', help_page_path('user/permissions')
    ```
 
+#### Linking to `/help` in JavaScript
+
+To link to the documentation from a JavaScript or a Vue component, use the `helpPagePath` function from [`help_page_helper.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/helpers/help_page_helper.js):
+
+```javascript
+import { helpPagePath } from '~/helpers/help_page_helper';
+
+helpPagePath('user/permissions', { anchor: 'anchor-link' })
+// evaluates to '/help/user/permissions#anchor-link' for GitLab.com
+```
+
+This is preferred over static paths, as the helper also works on instances installed under a [relative URL](../../install/relative_url.md).
+
 ### GitLab `/help` tests
 
 Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/features/help_pages_spec.rb)

spec/frontend/helpers/help_page_helper_spec.js

+import { helpPagePath } from '~/helpers/help_page_helper';
+
+describe('help page helper', () => {
+  it.each`
+    relative_url_root | path                         | anchor                  | expected
+    ${undefined}      | ${'administration/index'}    | ${undefined}            | ${'/help/administration/index'}
+    ${''}             | ${'administration/index'}    | ${undefined}            | ${'/help/administration/index'}
+    ${'/'}            | ${'administration/index'}    | ${undefined}            | ${'/help/administration/index'}
+    ${'/gitlab'}      | ${'administration/index'}    | ${undefined}            | ${'/gitlab/help/administration/index'}
+    ${'/gitlab/'}     | ${'administration/index'}    | ${undefined}            | ${'/gitlab/help/administration/index'}
+    ${undefined}      | ${'administration/index'}    | ${undefined}            | ${'/help/administration/index'}
+    ${'/'}            | ${'administration/index'}    | ${undefined}            | ${'/help/administration/index'}
+    ${''}             | ${'administration/index.md'} | ${undefined}            | ${'/help/administration/index.md'}
+    ${''}             | ${'administration/index.md'} | ${'installing-gitlab'}  | ${'/help/administration/index.md#installing-gitlab'}
+    ${''}             | ${'administration/index'}    | ${'installing-gitlab'}  | ${'/help/administration/index#installing-gitlab'}
+    ${''}             | ${'administration/index'}    | ${'#installing-gitlab'} | ${'/help/administration/index#installing-gitlab'}
+    ${''}             | ${'/administration/index'}   | ${undefined}            | ${'/help/administration/index'}
+    ${''}             | ${'administration/index/'}   | ${undefined}            | ${'/help/administration/index/'}
+    ${''}             | ${'/administration/index/'}  | ${undefined}            | ${'/help/administration/index/'}
+    ${'/'}            | ${'/administration/index'}   | ${undefined}            | ${'/help/administration/index'}
+  `(
+    'generates correct URL when path is `$path`, relative url is `$relative_url_root` and anchor is `$anchor`',
+    ({ relative_url_root, anchor, path, expected }) => {
+      window.gon = { relative_url_root };
+
+      expect(helpPagePath(path, { anchor })).toBe(expected);
+    },
+  );
+});