Allow /help to accept either index.md or _index.md as a docs index page

Changelog: changed

app/controllers/help_controller.rb

@@ -12,7 +12,7 @@ class HelpController < ApplicationController
   YAML_FRONT_MATTER_REGEXP = /\A(---\s*\n.*?\n?)^((---|\.\.\.)\s*$\n?)/m
 
   def index
-    @help_index = get_markdown_without_frontmatter(path_to_doc('index.md'))
+    @help_index = markdown_for(path_to_doc('index.md'))
 
     # Prefix Markdown links with `help/` unless they are external links.
     # '//' not necessarily part of URL, e.g., mailto:mail@example.com
@@ -115,9 +115,9 @@ def render_documentation
     # Note: We are purposefully NOT using `Rails.root.join` because of https://gitlab.com/gitlab-org/gitlab/-/issues/216028.
     path = path_to_doc("#{@path}.md")
 
-    if File.exist?(path)
-      @markdown = get_markdown_without_frontmatter(path)
+    @markdown = markdown_for(path)
 
+    if @markdown
       render :show, formats: :html
     else
       # Force template to Haml
@@ -128,6 +128,18 @@ def render_documentation
   def path_to_doc(file_name)
     File.join(Rails.root, 'doc', file_name)
   end
+
+  def markdown_for(raw_path)
+    if File.exist?(raw_path)
+      path = raw_path
+    elsif raw_path.ends_with?('index.md')
+      munged_path = raw_path.gsub('index.md', '_index.md')
+
+      path = munged_path if File.exist?(munged_path)
+    end
+
+    path ? get_markdown_without_frontmatter(path) : nil
+  end
 end
 
 ::HelpController.prepend_mod

doc/administration/settings/help_page.md

@@ -82,7 +82,8 @@ You can redirect all `/help` links to a destination that meets the [necessary re
 1. In the **Documentation pages URL** field, enter the URL.
 1. Select **Save changes**.
 
-If the "Documentation pages URL" field is empty, the 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.
+If the **Documentation pages URL** field is empty, the 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.
 
 ### Destination requirements
 

doc/development/documentation/help.md

@@ -31,6 +31,34 @@ For example:
 If it is important that a documentation update is present in that month's release,
 merge it as early as possible.
 
+## Page mapping
+
+Requests to `/help` can be [redirected](../../administration/settings/help_page.md#redirect-help-pages). If redirection
+is turned off, `/help` maps requests for help pages to specific files in the `doc`
+directory. For example:
+
+- Requested URLs: `<gdk_instance>/help/topics/plan_and_track.md`, `<gdk_instance>/help/topics/plan_and_track.html`
+  and `<gdk_instance>/help/topics/plan_and_track`.
+- Mapping: `doc/topics/plan_and_track.md`.
+
+### `_index.md` files
+
+> - Support for `_index.md` files [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144419) in GitLab 16.10.
+
+The Hugo static site generator makes use of `_index.md` files. To allow for index pages to be
+named either `index.md` or `_index.md` in `/help`, GitLab maps requests for `index.md`, `index.html`, or `index`:
+
+- To `index.md` if the file exists at the requested location.
+- Otherwise, to `_index.md`.
+
+For example:
+
+- Requested URLs: `<gdk_instance>/help/user/index.md`, `<gdk_instance>/help/user/index.html`, and
+  `<gdk_instance>/help/user/index`.
+- Mapping:
+  - `doc/user/index.md` if it exists.
+  - Otherwise, to `doc/user/_index.md`.
+
 ## Linking to `/help`
 
 When you're building a new feature, you may need to link to the documentation

spec/controllers/help_controller_spec.rb

@@ -137,6 +137,34 @@
         expect(response).not_to redirect_to(profile_two_factor_auth_path)
       end
     end
+
+    context 'when requesting help index' do
+      subject { get :index }
+
+      before do
+        stub_application_setting(help_page_documentation_base_url: '')
+      end
+
+      context 'and the doc/index.md file exists' do
+        it 'returns index.md' do
+          expect(subject).to be_successful
+          expect(assigns[:help_index]).to include('Explore the different areas of the documentation')
+        end
+      end
+
+      context 'but the doc/index.md file does not exist' do
+        it 'returns _index.md' do
+          stub_doc_file_read(content: '_index.md content', file_name: '_index.md')
+
+          allow(File).to receive(:exist?).and_call_original
+          allow(File).to receive(:exist?).with(Rails.root.join('doc/index.md').to_s).and_return(false)
+          allow(File).to receive(:exist?).with(Rails.root.join('doc/_index.md').to_s).and_return(true)
+
+          expect(subject).to be_successful
+          expect(assigns[:help_index]).to eq '_index.md content'
+        end
+      end
+    end
   end
 
   describe 'GET #drawers' do
@@ -290,6 +318,36 @@
         expect(response).to be_not_found
       end
     end
+
+    context 'when requesting an index.md' do
+      let(:path) { 'index' }
+
+      subject { get :show, params: { path: path }, format: :md }
+
+      before do
+        stub_application_setting(help_page_documentation_base_url: '')
+      end
+
+      context 'and the index.md file exists' do
+        it 'returns an index.md file' do
+          expect(subject).to be_successful
+          expect(assigns[:markdown]).to include('Explore the different areas of the documentation')
+        end
+      end
+
+      context 'but the index.md file does not exist' do
+        it 'returns an _index.md file' do
+          stub_doc_file_read(content: '_index.md content', file_name: '_index.md')
+
+          allow(File).to receive(:exist?).and_call_original
+          allow(File).to receive(:exist?).with(Rails.root.join('doc/index.md').to_s).and_return(false)
+          allow(File).to receive(:exist?).with(Rails.root.join('doc/_index.md').to_s).and_return(true)
+
+          expect(subject).to be_successful
+          expect(assigns[:markdown]).to eq '_index.md content'
+        end
+      end
+    end
   end
 
   def stub_two_factor_required