Skip to content

Add support for _index.md files as repository landing pages

Achilleas Pipinellisrequested to merge
axil-add-index-md-support into master

What does this MR do and why?

This was crafted with the help of GitLab Duo Agent.

Adds support for _index.md files as repository landing pages, making them render automatically alongside README and index files.

Changes Made

Backend (Minimal Changes):

  • lib/gitlab/markup_helper.rb: Added _index to PLAIN_FILENAMES array in priority order: %w[readme index _index]
  • Tests: Added _index file detection tests to spec/lib/gitlab/file_detector_spec.rb and spec/models/tree_spec.rb

Frontend (Key Fix):

  • app/assets/javascripts/repository/utils/readme.js:
    • Changed FILENAMES array to ['readme', 'index', '_index'] (priority order)
    • Rewrote readmeFile() function to respect priority order by checking patterns sequentially
    • Previously used .find() which was order-dependent on the blobs array
    • Now iterates through patterns in priority order, ensuring deterministic selection

Documentation:

  • Updated doc/user/project/repository/files/_index.md to document the new feature and priority order

Priority Order (Deterministic)

  1. README files (highest priority)
  2. index files
  3. _index files (lowest priority)

Within each category:

  • Previewable files (with markup extensions like .md, .rst) take precedence over plain text
  • Alphabetical ordering as tie-breaker (e.g., README.adoc before README.md)

Why This Matters

  • Hugo compatibility: Hugo-based projects use _index.md for section pages
  • Deterministic behavior: Frontend now respects priority order regardless of filesystem ordering
  • Backward compatible: Existing README and index files maintain their precedence

References

Discussed in gitlab-environment-toolkit#192 (comment 2771576958) and I thought that would be an easy task. It wasn't 😄 Got it working though with the help of Duo agent. However, it overly complicated things, when there was a much easier path. Human 1, machine 0.

Blast from the past when we did the same with index.md 😄

Screenshots or screen recordings

Before After
Screenshot_2025-09-26_at_16-37-27_Administrator___Test123___GitLab Screenshot_2025-09-26_at_16-37-05_Administrator___Test123___GitLab

Test with mixes

Description Screenshot
All files, README.adoc is rendered Screenshot_2025-09-30_at_16-48-38_all___main___Administrator___Test123___GitLab
Removed README.adoc, README.md is rendered Screenshot_2025-09-30_at_16-49-07_all___main___Administrator___Test123___GitLab
Removed README.md, index.md is rendered Screenshot_2025-10-03_at_22-50-16_indexes___main___Administrator___Test123___GitLab
Removed index.md, _index.md is rendered Screenshot_2025-10-03_at_22-51-24_indexes___main___Administrator___Test123___GitLab
Readded README.md, README.md is rendered Screenshot_2025-10-03_at_22-54-25_indexes___main___Administrator___Test123___GitLab

How to set up and validate locally

  1. Set up GDK.
  2. Check out this branch.
  3. Create a new project and import by URL the following testing repo: 
    https://gitlab.com/axil/indexes.git
  4. Navigate to the various directories and validate it works as expected (README.md > index.md > _index.md).

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Achilleas Pipinellis

Merge request reports