jekyll-documents 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be2955da22172cc24f7aed4e3dca0ac968bf131040a36db5fe2ba048a64bca90
-  data.tar.gz: 2b3d0544fa7c86739e2d83cd9228ee24c64f6bc4ff7691211aefbc7f3533f837
+  metadata.gz: 34e9456980c65a0eab294a17100d6de0bcf522bc3652afcadc3c2521c8c9d48b
+  data.tar.gz: be4ff590ed8c3e251fb7c56a1e57a33e2650d60a63c44113bb2a4c48402fe906
 SHA512:
-  metadata.gz: 1f2c7c21a5cdd8c5e996379467b2ceb38d69e368aa9f8bdae882a657366911fb1262f66a7c8ff549d848b1304fd90a8e56e9f37efe1b856f572fab550899d3d5
-  data.tar.gz: fce8b514c14788e75405a026dcd6e7eabf25955a12ac16445380f995728cf6f2c65099ab42af18c51c8fb2c1361f3f3bb9cdfa1845a3642e4495e532640a7d16
+  metadata.gz: 4c456c2e5ff0b55a6d51bc777770bed926b6cfa4c8a1393fda110f5d0a8d3e0e49af5c5399e1a0bdf2f4c8f5632e19ec8490975722842a5657b9f6e737c4412a
+  data.tar.gz: 5ff47c4204e58ad1e49bd48cd146d4f51ccf44254f1244530b0fd39f8fa2b5817531cfa293409a3f6fbad7063bc3425599e2c1bf37d094b5dbb45bba5cc13dc8

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-## [Unreleased]
+## [0.7.0] - 2026-09-05
+
+### Added
+- Added stable `source_path`, `category_path`, and `category_slug` document metadata and JSON index fields
+- Added exact `path:` resolution for document and category tags plus explicit category aggregation
+- Added path/date permalink placeholders and full-path-first category mappings
+- Added configurable `warn` or `strict` handling for unresolved and ambiguous tag references
+
+### Fixed
+- Ambiguous tags no longer silently select the first match
+- Duplicate generated permalinks now abort the build and identify every conflicting source file
 
 ## [0.6.1] - 2026-09-03
 

data/README.md

@@ -90,24 +90,27 @@ The tag applies the configured icon set and site `baseurl` automatically. The `f
 {% doc_link "Annual Report" %}
 {% doc_link "annual" text:"Read the report" %}
 {% doc_link "board-meeting" icon:false size:false %}
+{% doc_link path:"Reports/2026-03-01_Annual_Report.pdf" %}
 ```
 
 Renders an `<a>` tag with the file type icon, title, and human-readable file size.
 Use `text:"..."` to override the link text, `icon:false` to hide the icon,
-or `size:false` to hide the file size.
+or `size:false` to hide the file size. A `path:` lookup is exact and case-sensitive after
+normalizing `/` and `\` separators; use it when a title or slug matches multiple documents.
 
 **Link to or list a category**:
 
 ```liquid
 {% doc_category "reports" %}
 {% doc_category "reports" text:"All reports" %}
-{% doc_category "reports" list:true %}
 {% doc_category "reports" list:true limit:5 %}
+{% doc_category path:"Departments/Europe/Reports" list:true %}
+{% doc_category "reports" aggregate:true list:true %}
 ```
 
-Link mode renders an `<a>` tag to the category page.
-List mode renders a `<ul>` of all documents in the category, sorted by date descending.
-Use `limit:N` to cap the number of items.
+Link mode renders an `<a>` tag to the category page. List mode renders a `<ul>` sorted by date.
+Use `path:` for an exact, case-sensitive category path, `limit:N` to cap the list, and
+`aggregate:true list:true` to explicitly combine repeated short category names.
 
 ## Configuration
 
@@ -116,8 +119,29 @@ documents:
   root: "assets/documents"
   icon_set: "color"
   strict_filename: true
+  resolution_mode: "warn"
 ```
 
+`resolution_mode` controls ambiguous or unknown path references. The default `warn` mode logs
+all matching candidates and renders nothing. Set it to `strict` to log the same diagnostic and
+abort the build.
+
+Generated documents expose `source_path`, `category_path`, and `category_slug`. Category mappings
+check the complete `category_path` before falling back to its final directory component.
+Permalinks support `:category`, `:category_path`, `:slug`, `:source_path`, `:date`, `:year`,
+`:month`, and `:day`. For example:
+
+```yaml
+documents:
+  permalink: "/documents/:category_path/:date/:slug/"
+  category_map:
+    Departments/Europe/Research: "European Research"
+    Research: "Research"
+```
+
+The default permalink remains backward compatible. Any duplicate final permalink is fatal and
+the build error lists every conflicting `source_path`.
+
 See [configuration.rb](lib/jekyll/documents/configuration.rb) for all options.
 
 ## Icon sizing

data/lib/jekyll/documents/configuration.rb

@@ -2,7 +2,19 @@
 
 module Jekyll
   module Documents
+    module ResolutionReporter
+      private
+
+      def report_resolution_issue(site, message)
+        method = Configuration.read(site)["resolution_mode"].to_s == "strict" ? :abort_with : :warn
+        ::Jekyll.logger.public_send(method, "jekyll-documents", message)
+      end
+    end
+
     class Configuration
+      RESOLUTION_MODES = %w[warn strict].freeze
+      private_constant :RESOLUTION_MODES
+
       DEFAULTS = {
         "root" => "assets/documents",
         "permalink" => "/documents/:category/:slug/",
@@ -19,6 +31,7 @@ module Jekyll
         # Validation
         "strict_filename" => true,
         "strict_extensions" => true,
+        "resolution_mode" => "warn",
 
         # JSON Index for Lunr
         "json_index" => true,
@@ -34,8 +47,13 @@ module Jekyll
       }.freeze
 
       def self.read(site)
-        cfg = site.config["documents"] || {}
-        DEFAULTS.merge(cfg)
+        cfg = DEFAULTS.merge(site.config["documents"] || {})
+        mode = cfg["resolution_mode"].to_s
+        unless RESOLUTION_MODES.include?(mode)
+          ::Jekyll.logger.abort_with "jekyll-documents",
+                                     "resolution_mode must be warn or strict, got #{mode.inspect}"
+        end
+        cfg
       end
     end
   end

data/lib/jekyll/documents/generator.rb

@@ -37,23 +37,26 @@ module Jekyll
         end
 
         collection = ensure_collection(site, "documents")
-
         current_paths = []
+        generated_docs = []
 
         Dir.glob("#{root}/**/*").each do |path|
           next unless File.file?(path)
 
-          ext = File.extname(path).downcase
+          source_extension = File.extname(path)
+          ext = source_extension.downcase
           if @config["strict_extensions"] && !@config["include_extensions"].include?(ext)
             ::Jekyll.logger.abort_with "jekyll-documents",
                                        "Unsupported file type: #{path} (#{ext})"
           end
           next unless @config["include_extensions"].include?(ext)
 
-          rel_path = path.delete_prefix("#{site.source}/")
+          source_path = source_path_for(path, root)
+          category_path = document_category_path(source_path)
+          category = remap_category(category_path)
+          rel_path = normalize_path(File.join(@config["root"], source_path))
           current_paths << rel_path
-          category = infer_category_from(rel_path)
-          basename = File.basename(path, ext)
+          basename = File.basename(path, source_extension)
 
           date, title, valid = parse_filename(basename)
           if !valid && @config["strict_filename"]
@@ -61,23 +64,23 @@ module Jekyll
                                        "Filename must be 'YYYY-MM-DD_Title.ext' → #{rel_path}"
           end
 
-          slug = build_slug(basename)
-          file_type = ext.sub(".", "").downcase
-          icon_set = @config["icon_set"]
-
           doc = ::Jekyll::Document.new(
-            source_stub_for(basename, category),
+            source_stub_for(source_path),
             site: site,
             collection: collection
           )
-
-          file_info = { title: title, date: date, category: category,
-                        rel_path: rel_path, ext: ext, file_type: file_type,
-                        icon_set: icon_set, slug: slug, path: path }
+          file_info = {
+            title: title, date: date, category: category, category_path: category_path,
+            category_slug: slugify(category, "uncategorized"), source_path: source_path,
+            rel_path: rel_path, ext: ext, file_type: ext.delete_prefix("."),
+            icon_set: @config["icon_set"], slug: build_slug(basename), path: path
+          }
           bake_document_data(doc, file_info)
           collection.docs << doc
+          generated_docs << doc
         end
 
+        detect_permalink_collisions(generated_docs)
         cleanup_manifest(current_paths) if @config["extract_text"]
         configure_client_search(site)
       end
@@ -205,23 +208,22 @@ module Jekyll
 
       def bake_document_data(doc, info)
         data = doc.data
-        category = remap_category(info[:category])
-        data["layout"]     = @config["layout"]
-        data["title"]      = info[:title]
-        data["date"]       = info[:date] ? info[:date].to_time : File.mtime(info[:path])
-        data["category"]   = category
-        data["categories"] = [category] if category
-        data["file_url"]   = "/#{info[:rel_path]}"
-        data["extension"]  = info[:ext]
-        data["file_type"]  = info[:file_type]
-        data["icon_set"]   = info[:icon_set]
-        icon = FileTypeIcons.icon_for(info[:file_type], info[:icon_set])
-        data["icon_url"]   = icon
-        data["file_size"]  = File.size(info[:path])
-        data["slug"]       = info[:slug]
-        data["permalink"]  = @config["permalink"]
-                             .gsub(":category", category.to_s)
-                             .gsub(":slug", info[:slug])
+        data["layout"]        = @config["layout"]
+        data["title"]         = info[:title]
+        data["date"]          = info[:date] ? info[:date].to_time : File.mtime(info[:path])
+        data["category"]      = info[:category]
+        data["category_path"] = info[:category_path]
+        data["category_slug"] = info[:category_slug]
+        data["categories"]    = [info[:category]] if info[:category]
+        data["source_path"]   = info[:source_path]
+        data["file_url"]      = "/#{info[:rel_path]}"
+        data["extension"]     = info[:ext]
+        data["file_type"]     = info[:file_type]
+        data["icon_set"]      = info[:icon_set]
+        data["icon_url"]      = FileTypeIcons.icon_for(info[:file_type], info[:icon_set])
+        data["file_size"]     = File.size(info[:path])
+        data["slug"]          = info[:slug]
+        data["permalink"]     = expand_permalink(data)
         metadata_content = searchable_content(info[:title], data, info[:file_type])
         doc.content = if @config["extract_text"]
                         extracted_content = extract_file_content(info)
@@ -236,11 +238,10 @@ module Jekyll
       end
 
       # Creates a virtual source path for the document
-      # @param basename [String] the file basename
-      # @param category [String] the document category
+      # @param source_path [String] the unique path below the documents root
       # @return [String] virtual source path
-      def source_stub_for(basename, category)
-        File.join("_documents", "#{category}-#{basename}.md")
+      def source_stub_for(source_path)
+        File.join("_documents", "#{normalize_path(source_path)}.md")
       end
 
       # Infers category from the file's directory path
@@ -249,16 +250,80 @@ module Jekyll
       def infer_category_from(rel_path)
         return "uncategorized" unless @config["categories_from_path"]
 
-        category_dir = File.dirname(rel_path).sub(@config["root"].to_s, "")
-        category_dir.split("/").reject(&:empty?).last || "uncategorized"
+        source_path = source_path_for(rel_path, @config["root"])
+        category_path_for(source_path).split("/").last || "uncategorized"
       end
 
       # Remaps category name using category_map configuration
       # @param cat [String] the original category
-      # @return [String] the remapped category (lowercased)
+      # @return [String] the mapped display category or lowercased directory name
       def remap_category(cat)
         map = @config["category_map"] || {}
-        (map[cat] || cat).to_s.downcase
+        leaf = cat.to_s.split("/").last || "uncategorized"
+        mapped = map[cat] || map[leaf]
+        mapped ? mapped.to_s : leaf.downcase
+      end
+
+      def normalize_path(path)
+        path.to_s.tr("\\", "/").squeeze("/").delete_prefix("/").delete_suffix("/")
+      end
+
+      def source_path_for(path, root)
+        normalized_path = normalize_path(path)
+        normalized_root = normalize_path(root)
+        normalized_path.delete_prefix("#{normalized_root}/")
+      end
+
+      def category_path_for(source_path)
+        path = normalize_path(source_path)
+        path.include?("/") ? path.rpartition("/").first : "uncategorized"
+      end
+
+      def document_category_path(source_path)
+        @config["categories_from_path"] ? category_path_for(source_path) : "uncategorized"
+      end
+
+      def expand_permalink(data)
+        values = permalink_values(data)
+        @config["permalink"].gsub(/:([a-z_]+)/) do |placeholder|
+          values.fetch(Regexp.last_match(1), placeholder)
+        end
+      end
+
+      def permalink_values(data)
+        date = data["date"]
+        {
+          "category" => data["category_slug"],
+          "category_path" => slugify_path(data["category_path"]),
+          "slug" => data["slug"],
+          "date" => date.strftime("%Y-%m-%d"),
+          "year" => date.strftime("%Y"),
+          "month" => date.strftime("%m"),
+          "day" => date.strftime("%d"),
+          "source_path" => source_path_url(data["source_path"])
+        }
+      end
+
+      def slugify_path(path)
+        normalize_path(path).split("/").map { |segment| slugify(segment, "untitled") }.join("/")
+      end
+
+      def source_path_url(source_path)
+        extension = File.extname(source_path)
+        stem = source_path.delete_suffix(extension)
+        "#{slugify_path(stem)}#{extension.downcase}"
+      end
+
+      def detect_permalink_collisions(docs)
+        collisions = docs.group_by(&:url).select { |_url, matches| matches.size > 1 }
+        return if collisions.empty?
+
+        details = collisions.sort.map do |url, matches|
+          paths = matches.map { |doc| doc.data["source_path"] }.sort.join(", ")
+          "#{url}: #{paths}"
+        end
+        ::Jekyll.logger.abort_with "jekyll-documents",
+                                   "Permalink collision detected:\n#{details.join("\n")}"
       end
 
       # Parses filename to extract date and title
@@ -283,7 +348,11 @@ module Jekyll
       # @param basename [String] the filename without extension
       # @return [String] the generated slug
       def build_slug(basename)
-        slug = basename.sub(/^\d{4}-\d{2}-\d{2}_/, "")
+        slugify(basename.sub(/^\d{4}-\d{2}-\d{2}_/, ""), "untitled")
+      end
+
+      def slugify(value, fallback)
+        slug = value.to_s
         if @config["slug_danish_map"]
           slug = slug.gsub(/[æøåÆØÅ]/,
                            { "æ" => "ae", "ø" => "oe", "å" => "aa", "Æ" => "Ae", "Ø" => "Oe",
@@ -292,7 +361,7 @@ module Jekyll
         slug = slug.downcase if @config["slug_downcase"]
         slug = slug.gsub(/[^\p{Alnum}\-_\s]/u, "").tr("_ ", "--").squeeze("-")
         slug = slug.sub(/^-+/, "").sub(/-+$/, "")
-        slug.empty? ? "untitled" : slug
+        slug.empty? ? fallback : slug
       end
     end
   end

data/lib/jekyll/documents/json_index_generator.rb

@@ -22,6 +22,9 @@ module Jekyll
             "url" => doc.url,
             "title" => data["title"],
             "category" => data["category"],
+            "category_path" => data["category_path"],
+            "category_slug" => data["category_slug"],
+            "source_path" => data["source_path"],
             "date" => (data["date"] || Time.at(0)).strftime("%Y-%m-%d"),
             "slug" => data["slug"],
             "file_type" => data["file_type"],

data/lib/jekyll/documents/tags/doc_category.rb

@@ -2,9 +2,63 @@
 
 module Jekyll
   module Documents
+    module CategoryResolver
+      include ResolutionReporter
+
+      private
+
+      def resolve_category(query, options, categories, site)
+        return resolve_category_path(options["path"], categories, site) if options["path"]
+
+        normalized = query.to_s.strip.downcase
+        return nil if normalized.empty?
+
+        exact = categories.select do |category|
+          category_values(category).include?(normalized)
+        end
+        matches = exact.empty? ? partial_categories(categories, normalized) : exact
+        aggregate = options["aggregate"] == "true" && options["list"] == "true"
+        return matches if matches.one? || (aggregate && matches.any?)
+        return nil if matches.empty?
+
+        paths = matches.map { |category| category["path"] }.sort.join(", ")
+        message = "Ambiguous doc_category #{query.inspect}; matches: #{paths}. Rendering nothing."
+        report_resolution_issue(site, message)
+        nil
+      end
+
+      def resolve_category_path(path, categories, site)
+        normalized = normalize_category_path(path)
+        matches = categories.select { |category| category["path"] == normalized }
+        return matches if matches.one?
+
+        issue = matches.empty? ? "Unknown" : "Ambiguous"
+        report_resolution_issue(site,
+                                "#{issue} doc_category path #{path.inspect}: #{normalized}")
+        nil
+      end
+
+      def partial_categories(categories, query)
+        categories.select do |category|
+          category_values(category).any? { |value| value.include?(query) }
+        end
+      end
+
+      def category_values(category)
+        leaf = category["path"].split("/").last.to_s.downcase
+        [category["category"], category["slug"], leaf].map { |value| value.to_s.downcase }.uniq
+      end
+
+      def normalize_category_path(path)
+        path.to_s.strip.tr("\\", "/").squeeze("/").delete_prefix("./").delete_prefix("/")
+            .delete_suffix("/")
+      end
+    end
+
     class DocCategoryTag < Liquid::Tag
       public_class_method :new
 
+      include CategoryResolver
       include Jekyll::Filters::URLFilters
 
       def initialize(tag_name, markup, tokens)
@@ -17,13 +71,13 @@ module Jekyll
         return "" if docs.empty?
 
         categories = available_categories(docs)
-        category = resolve_category(@category, categories)
-        return "" unless category
+        matches = resolve_category(@category, @options, categories, context.registers[:site])
+        return "" unless matches
 
         @context = context
-        return render_list(docs, category) if @options["list"] == "true"
+        return render_list(docs, matches) if @options["list"] == "true"
 
-        render_link(category)
+        render_link(matches)
       end
 
       private
@@ -34,36 +88,39 @@ module Jekyll
       end
 
       def available_categories(docs)
-        docs.map { |doc| doc.data["category"].to_s }.uniq.sort
-      end
-
-      def resolve_category(query, categories)
-        normalized = query.to_s.strip.downcase
-        return nil if normalized.empty?
-
-        categories.find { |cat| cat.downcase == normalized } ||
-          categories.find { |cat| cat.downcase.include?(normalized) }
+        categories = docs.group_by { |doc| doc.data["category_path"] || doc.data["category"] }
+                         .map do |path, matches|
+          data = matches.first.data
+          { "path" => path.to_s, "category" => data["category"],
+            "slug" => data["category_slug"] || data["category"] }
+        end
+        categories.sort_by { |category| category["path"] }
       end
 
-      def render_link(category)
-        url = relative_url("/documents/#{category}/")
-        text = @options["text"] || category
+      def render_link(matches)
+        category = matches.first
+        url = relative_url("/documents/#{category['slug']}/")
+        text = @options["text"] || category["category"]
         %(<a href="#{escape_html(url)}">#{escape_html(text)}</a>)
       end
 
-      def render_list(docs, category)
-        cat_docs = sorted_category_docs(docs, category)
+      def render_list(docs, matches)
+        paths = matches.map { |category| category["path"] }
+        cat_docs = sorted_category_docs(docs, paths)
         limit = @options["limit"]&.to_i
         cat_docs = cat_docs.first(limit) if limit&.positive?
 
+        category = paths.join(",")
         out = %(<ul class="doc-category-list" data-category="#{escape_html(category)}">\n)
         out << list_items(cat_docs)
         out << "</ul>\n"
       end
 
-      def sorted_category_docs(docs, category)
-        docs.select { |doc| doc.data["category"].to_s == category }
-            .sort_by { |doc| doc.data["date"] || Time.at(0) }.reverse
+      def sorted_category_docs(docs, paths)
+        matches = docs.select do |doc|
+          paths.include?((doc.data["category_path"] || doc.data["category"]).to_s)
+        end
+        matches.sort_by { |doc| doc.data["date"] || Time.at(0) }.reverse
       end
 
       def list_items(cat_docs)
@@ -83,6 +140,8 @@ module Jekyll
       end
 
       def extract_category(text)
+        return [nil, text] if text.strip.match?(/\Apath\s*:/)
+
         quoted = text.match(/\A["']([^"']+)["']/)
         return [quoted[1], text[quoted.end(0)..]] if quoted
 

data/lib/jekyll/documents/tags/doc_link.rb

@@ -2,9 +2,60 @@
 
 module Jekyll
   module Documents
+    module DocumentResolver
+      include ResolutionReporter
+
+      private
+
+      def find_document(docs, query, options, site)
+        return find_document_by_path(docs, options["path"], site) if options["path"]
+
+        normalized = query.to_s.strip.downcase
+        return nil if normalized.empty?
+
+        exact = docs.select { |doc| document_values(doc).include?(normalized) }
+        matches = if exact.empty?
+                    docs.select do |doc|
+                      document_values(doc).any? { |value| value.include?(normalized) }
+                    end
+                  else
+                    exact
+                  end
+        return matches.first if matches.one?
+        return nil if matches.empty?
+
+        paths = matches.map { |doc| doc.data["source_path"] || doc.path }.sort.join(", ")
+        message = "Ambiguous doc_link #{query.inspect}; matches: #{paths}. Rendering nothing."
+        report_resolution_issue(site, message)
+        nil
+      end
+
+      def find_document_by_path(docs, path, site)
+        normalized = normalize_identifier_path(path)
+        matches = docs.select { |doc| doc.data["source_path"].to_s == normalized }
+        return matches.first if matches.one?
+
+        issue = matches.empty? ? "Unknown" : "Ambiguous"
+        candidates = matches.map { |doc| doc.data["source_path"] }.sort.join(", ")
+        detail = candidates.empty? ? normalized : candidates
+        report_resolution_issue(site, "#{issue} doc_link path #{path.inspect}: #{detail}")
+        nil
+      end
+
+      def normalize_identifier_path(path)
+        path.to_s.strip.tr("\\", "/").squeeze("/").delete_prefix("./").delete_prefix("/")
+            .delete_suffix("/")
+      end
+
+      def document_values(doc)
+        [doc.data["title"], doc.data["slug"]].map { |value| value.to_s.downcase }
+      end
+    end
+
     class DocLinkTag < Liquid::Tag
       public_class_method :new
 
+      include DocumentResolver
       include Jekyll::Filters::URLFilters
 
       SIZE_UNITS = %w[B KB MB GB].freeze
@@ -18,7 +69,7 @@ module Jekyll
         docs = documents_from(context)
         return "" if docs.empty?
 
-        match = find_document(docs, @query)
+        match = find_document(docs, @query, @options, context.registers[:site])
         return "" unless match
 
         @context = context
@@ -35,20 +86,6 @@ module Jekyll
         site.collections["documents"]&.docs || []
       end
 
-      def find_document(docs, query)
-        normalized = query.to_s.strip.downcase
-        return nil if normalized.empty?
-
-        docs.find { |doc| matches?(doc, normalized) }
-      end
-
-      def matches?(doc, query)
-        title = doc.data["title"].to_s.downcase
-        slug = doc.data["slug"].to_s.downcase
-        title == query || slug == query ||
-          title.include?(query) || slug.include?(query)
-      end
-
       def build_link(doc, url, text)
         inner = +""
         inner << icon_html(doc) if @options["icon"] != "false"
@@ -99,6 +136,8 @@ module Jekyll
       end
 
       def extract_query(text)
+        return [nil, text] if text.strip.match?(/\Apath\s*:/)
+
         quoted = text.match(/\A["']([^"']+)["']/)
         return [quoted[1], text[quoted.end(0)..]] if quoted
 

data/lib/jekyll/documents/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Documents
-    VERSION = "0.6.1"
+    VERSION = "0.7.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-documents
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Svend Gundestrup