jekyll-readme-index 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5bd74269cd40c7051ee807361769d9a049977d4270ee22d0c59db95adb98fea
-  data.tar.gz: 3b02a03d7b5a5184d0cb3743cf1e778302fb843f16acfaa898a9c7f1870db6a1
+  metadata.gz: a962fee2eeeb3f2afc21c0e7a4d99d50db52e11750358d7ea13a1cfc76ea5b01
+  data.tar.gz: ed15d139b9f068004a0a7e36defdc56bcfd2fc289299f404548531724b18dad5
 SHA512:
-  metadata.gz: 698899c2dd728705703b01002c82854e18b49728eef9f0761caab3e179f05693322579a0fcfdcfb1e6625f0a6ca0afe14220386f6e263daf6b2b11d0e5f04d19
-  data.tar.gz: 51953c2dd58f121c858b6ff20e712ba20093c35936a517e3f3ebe4369162086daf792fd6ac3db8ae8689507a891f55976947ecf93c552441456880253d3c9b91
+  metadata.gz: 259e6eabc8d4b5ea02b77377f331099ec70413fede4d8dc4d2d9ef5ae9ca120d8cdb7892f17b54d00745f48277a0edd976e770d2a6eabba27940fefdedf36a85
+  data.tar.gz: d3770314f5f85253a15ad8b471f13ae6fe265f1b6eac759fd56cd62cff09ccd5fd8a8665ed644a5fb68e790ee717f806f1dca3f71fc3b7e54b54f6591d3429a6

data/lib/jekyll-readme-index/generator.rb

@@ -1,8 +1,17 @@
 # frozen_string_literal: true
 
+require "set"
+
 module JekyllReadmeIndex
   class Generator < Jekyll::Generator
-    INDEX_REGEX = %r!$|index\.(html?|xhtml|xml)$!i.freeze
+    # Captures the directory a URL is the index of, e.g. "/a/" for "/a/" or "/a/index.html"
+    INDEX_URL_REGEX = %r!\A(.*/)(?:index\.(?:html?|xhtml|xml))?\z!i.freeze
+    GITHUB_DIR = "/.github"
+    DOCS_DIR = "/docs"
+    SPECIAL_DIRS = [GITHUB_DIR, DOCS_DIR].freeze
+    GITHUB_README_PATTERN = %r!^/\.github/readme!i.freeze
+    DOCS_README_PATTERN = %r!^/docs/readme!i.freeze
+    ROOT_README_PATTERN = %r!^/readme!i.freeze
 
     attr_accessor :site
 
@@ -13,6 +22,7 @@ module JekyllReadmeIndex
     ENABLED_KEY = "enabled"
     CLEANUP_KEY = "remove_originals"
     FRONTMATTER_KEY = "with_frontmatter"
+    PATTERN_KEY = "readme_pattern"
 
     def initialize(site)
       @site = site
@@ -20,12 +30,15 @@ module JekyllReadmeIndex
 
     def generate(site)
       @site = site
+      @index_dirs = nil
       return if disabled?
 
       readmes.each do |readme|
         next unless should_be_index?(readme)
 
-        site.pages << readme.to_page
+        page = to_page(readme)
+        site.pages << page
+        add_index_dir(page.url)
         site.static_files.delete(readme) if cleanup?
       end
 
@@ -33,7 +46,7 @@ module JekyllReadmeIndex
         readmes_with_frontmatter.each do |readme|
           next unless should_be_index?(readme)
 
-          readme.update_permalink
+          add_index_dir(update_permalink(readme))
         end
       end
     end
@@ -42,32 +55,133 @@ module JekyllReadmeIndex
 
     # Returns an array of all READMEs as StaticFiles
     def readmes
-      site.static_files.select { |file| file.relative_path =~ readme_regex }
+      candidates = site.static_files.select { |file| file.relative_path =~ readme_regex }
+      prioritize_readmes(candidates)
     end
 
     def readmes_with_frontmatter
-      site.pages.select { |file| ("/" + file.path) =~ readme_regex }
+      candidates = site.pages.select { |file| ("/" + file.path) =~ readme_regex }
+      prioritize_readmes(candidates)
+    end
+
+    # Prioritize READMEs according to GitHub's order: .github > root > docs
+    # For each target directory, keep only the highest priority README
+    def prioritize_readmes(candidates)
+      grouped = candidates.group_by do |file|
+        # Get the directory that would become the index
+        # READMEs in .github and docs should serve as index for parent directory
+        # Note: file_path returns Jekyll-normalized paths without query strings
+        dir = File.dirname(file_path(file))
+
+        # If the README is in .github or docs subdirectory at root,
+        # it should be the index for root
+        if SPECIAL_DIRS.include?(dir)
+          "/"
+        else
+          dir
+        end
+      end
+
+      grouped.flat_map do |_dir, files|
+        # Sort by priority: .github first, then root, then docs, then others
+        files.min_by do |file|
+          case readme_path(file)
+          when GITHUB_README_PATTERN then 0
+          when ROOT_README_PATTERN then 1
+          when DOCS_README_PATTERN then 2
+          else 3
+          end
+        end
+      end.compact
+    end
+
+    # Convert a README StaticFile to a Page that serves as its directory's index
+    def to_page(static_file)
+      # StaticFile doesn't expose its base, dir, or name (the last only since
+      # Jekyll 4), so read them the same way jekyll-optional-front-matter does.
+      base = static_file.instance_variable_get(:@base)
+      dir  = static_file.instance_variable_get(:@dir)
+      name = static_file.instance_variable_get(:@name)
+      page = Jekyll::Page.new(site, base, dir, name)
+
+      page.data["permalink"] = target_dir(static_file)
+      page
+    end
+
+    # Point a README Page's permalink at its directory
+    def update_permalink(page)
+      # If URL already ends with '/', it's a directory URL and should be used as-is
+      url = page.url
+      page.data["permalink"] = url.end_with?("/") ? url : target_dir(page)
+      # Page#url is memoized; drop it so it's rebuilt from the new permalink
+      page.instance_variable_set(:@url, nil)
+      page.url
+    end
+
+    # The directory a README should be the index for
+    def target_dir(file)
+      # For READMEs in .github or docs at root level, they should be the root index
+      return "/" if special_readme?(file)
+
+      File.join(File.dirname(file.url), "/")
+    end
+
+    # Check if this is a README in a special directory (.github or docs)
+    def special_readme?(file)
+      path = readme_path(file)
+      path =~ GITHUB_README_PATTERN || path =~ DOCS_README_PATTERN
+    end
+
+    # The file's path relative to the site source, with a leading slash.
+    #
+    # StaticFile#relative_path starts with "/", but Page#relative_path doesn't
+    # on Jekyll 4 (or for root pages on Jekyll 3), so the priority patterns
+    # never matched READMEs with front matter.
+    def readme_path(file)
+      path = file.relative_path
+      path.start_with?("/") ? path : "/#{path}"
     end
 
     # Should the given readme be the containing directory's index?
     def should_be_index?(readme)
       return false unless readme
 
-      !dir_has_index? File.dirname(readme.url)
+      !dir_has_index? target_dir(readme)
     end
 
     # Does the given directory have an index?
     #
     # relative_path - the directory path relative to the site root
     def dir_has_index?(relative_path)
-      relative_path << "/" unless relative_path.end_with? "/"
-      regex = %r!^#{Regexp.escape(relative_path)}#{INDEX_REGEX}!i
-      (site.pages + site.static_files).any? { |file| file.url =~ regex }
+      relative_path = File.join(relative_path, "/") unless relative_path.end_with?("/")
+      index_dirs.include?(relative_path.downcase)
+    end
+
+    # The (downcased) directories that already have an index page or file.
+    # Built once per generate instead of scanning every file for every README.
+    def index_dirs
+      @index_dirs ||= Set.new.tap do |dirs|
+        site.pages.each { |page| add_index_dir(page.url, dirs) }
+        site.static_files.each { |file| add_index_dir(file.url, dirs) }
+      end
+    end
+
+    def add_index_dir(url, dirs = index_dirs)
+      match = INDEX_URL_REGEX.match(url)
+      dirs << match[1].downcase if match
     end
 
     # Regexp to match a file path against to detect if the given file is a README
     def readme_regex
-      @readme_regex ||= %r!/readme(#{Regexp.union(markdown_converter.extname_list)})$!i
+      # Allow custom pattern override via configuration
+      @readme_regex ||= if (custom_pattern = option(PATTERN_KEY))
+                          Regexp.new(custom_pattern, Regexp::IGNORECASE)
+                        else
+                          # Match README in any directory, including .github, docs subdirectories
+                          # The pattern ensures .github and docs are only matched at path boundaries
+                          extensions = Regexp.union(markdown_converter.extname_list)
+                          %r!/(?:\.github/|docs/)?readme(#{extensions})$!i
+                        end
     end
 
     def markdown_converter
@@ -89,5 +203,10 @@ module JekyllReadmeIndex
     def with_frontmatter?
       option(FRONTMATTER_KEY) == true
     end
+
+    # Helper method to get the file path (URL or path) for a file object
+    def file_path(file)
+      file.respond_to?(:url) ? file.url : "/" + file.path
+    end
   end
 end

data/lib/jekyll-readme-index/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JekyllReadmeIndex
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/jekyll-readme-index.rb

@@ -2,7 +2,6 @@
 
 require "jekyll"
 require "jekyll-readme-index/generator"
-require_relative "./jekyll/static_file_ext"
 
 module JekyllReadmeIndex
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-readme-index
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Ben Balter
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -30,77 +29,146 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: kramdown-parser-gfm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.5'
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.5'
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.40'
+        version: '1.57'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.40'
+        version: '1.57'
 - !ruby/object:Gem::Dependency
   name: rubocop-jekyll
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: '0.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: '0.14'
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.23'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.23'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
-description: 
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tsort
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - ben.balter@github.com
 executables: []
@@ -110,12 +178,10 @@ files:
 - lib/jekyll-readme-index.rb
 - lib/jekyll-readme-index/generator.rb
 - lib/jekyll-readme-index/version.rb
-- lib/jekyll/static_file_ext.rb
 homepage: https://github.com/benbalter/jekyll-readme-index
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -123,15 +189,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Jekyll plugin to render a project's README as the site's index.
 test_files: []

data/lib/jekyll/static_file_ext.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Jekyll
-  class StaticFile
-    # Convert this static file to a Page
-    def to_page
-      page = Jekyll::Page.new(@site, @base, @dir, @name)
-      page.data["permalink"] = File.dirname(url) + "/"
-      page
-    end
-  end
-
-  class Page
-    def update_permalink
-      data["permalink"] = File.dirname(url) + "/"
-      @url = URL.new(
-        :template     => template,
-        :placeholders => url_placeholders,
-        :permalink    => permalink
-      ).to_s
-    end
-  end
-end