Merge branch '18933-render-index-like-readme' into 'master'

Render index.* like README.* when it's present in a directory

Closes #18933

See merge request gitlab-org/gitlab-ce!22639

changelogs/unreleased/18933-render-index-as-readme.yml

+---
+title: Make index.* render like README.* when it's present in a repository
+merge_request: 22639
+author: Jakub Jirutka
+type: added

doc/user/project/repository/index.md

@@ -53,6 +53,32 @@ To get started with the command line, please read through the
 
 Use GitLab's [file finder](../../../workflow/file_finder.md) to search for files in a repository.
 
+### Repository README and index files
+
+When a `README` or `index` file is present in a repository, its contents will be
+automatically pre-rendered by GitLab without opening it.
+
+They can either be plain text or have an extension of a supported markup language:
+
+- Asciidoc: `README.adoc` or `index.adoc`
+- Markdown: `README.md` or `index.md`
+- reStructuredText: `README.rst` or `index.rst`
+- Text: `README.txt` or `index.txt`
+
+Some things to note about precedence:
+
+1. When both a `README` and an `index` file are present, the `README` will always
+   take precedence.
+1. When more than one file is present with different extensions, they are
+   ordered alphabetically, with the exception of a file without an extension
+   which will always be last in precedence. For example, `README.adoc` will take
+   precedence over `README.md`, and `README.rst` will take precedence over
+   `README`.
+
+NOTE: **Note:**
+`index` files without an extension will not automatically pre-render. You'll
+have to explicitly open them to see their contents.
+
 ### Jupyter Notebook files
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2508) in GitLab 9.1
@@ -165,7 +191,7 @@ minutes.
 
 ![Repository Languages bar](img/repository_languages.png)
 
-Not all files are detected, among others; documentation, 
+Not all files are detected, among others; documentation,
 vendored code, and most markup languages are excluded. This behaviour can be
 adjusted by overriding the default. For example, to enable `.proto` files to be
 detected, add the following to `.gitattributes` in the root of your repository.

lib/gitlab/file_detector.rb

@@ -8,7 +8,7 @@ module Gitlab
   module FileDetector
     PATTERNS = {
       # Project files
-      readme: %r{\Areadme[^/]*\z}i,
+      readme: %r{\A(readme|index)[^/]*\z}i,
       changelog: %r{\A(changelog|history|changes|news)[^/]*\z}i,
       license: %r{\A((un)?licen[sc]e|copying)(\.[^/]+)?\z}i,
       contributing: %r{\Acontributing[^/]*\z}i,

lib/gitlab/markup_helper.rb

@@ -4,10 +4,11 @@ module Gitlab
   module MarkupHelper
     extend self
 
-    MARKDOWN_EXTENSIONS = %w(mdown mkd mkdn md markdown).freeze
-    ASCIIDOC_EXTENSIONS = %w(adoc ad asciidoc).freeze
-    OTHER_EXTENSIONS = %w(textile rdoc org creole wiki mediawiki rst).freeze
+    MARKDOWN_EXTENSIONS = %w[mdown mkd mkdn md markdown].freeze
+    ASCIIDOC_EXTENSIONS = %w[adoc ad asciidoc].freeze
+    OTHER_EXTENSIONS = %w[textile rdoc org creole wiki mediawiki rst].freeze
     EXTENSIONS = MARKDOWN_EXTENSIONS + ASCIIDOC_EXTENSIONS + OTHER_EXTENSIONS
+    PLAIN_FILENAMES = %w[readme index].freeze
 
     # Public: Determines if a given filename is compatible with GitHub::Markup.
     #
@@ -43,7 +44,7 @@ module Gitlab
     #
     # Returns boolean
     def plain?(filename)
-      extension(filename) == 'txt' || filename.casecmp('readme').zero?
+      extension(filename) == 'txt' || plain_filename?(filename)
     end
 
     def previewable?(filename)
@@ -55,5 +56,9 @@ module Gitlab
     def extension(filename)
       File.extname(filename).downcase.delete('.')
     end
+
+    def plain_filename?(filename)
+      PLAIN_FILENAMES.include?(filename.downcase)
+    end
   end
 end

spec/lib/gitlab/file_detector_spec.rb

@@ -15,7 +15,12 @@ describe Gitlab::FileDetector do
 
   describe '.type_of' do
     it 'returns the type of a README file' do
-      expect(described_class.type_of('README.md')).to eq(:readme)
+      %w[README readme INDEX index].each do |filename|
+        expect(described_class.type_of(filename)).to eq(:readme)
+        %w[.md .adoc .rst].each do |extname|
+          expect(described_class.type_of(filename + extname)).to eq(:readme)
+        end
+      end
     end
 
     it 'returns nil for a README file in a directory' do