jekyll-documents 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 989b1372181a7ca00444d25b5fab29751a077d9818c41cca1fe8c14208050214
-  data.tar.gz: 8215c9234df6eba090b83a296acd0c058a73ae3bd16b0d11fd2ce69e539d788e
+  metadata.gz: 34e9456980c65a0eab294a17100d6de0bcf522bc3652afcadc3c2521c8c9d48b
+  data.tar.gz: be4ff590ed8c3e251fb7c56a1e57a33e2650d60a63c44113bb2a4c48402fe906
 SHA512:
-  metadata.gz: ba352213f38733179f053f989cfe5f363dee453176f4d301629fa0d5ab34b5d4f3aad443e8f46bc9b4ee9106626d09cbc255544862b12ba05850259a5b8879e9
-  data.tar.gz: 911cb909b005316a55d1978127935cf1bbf6da093c5dd0a9b6ec9e66112a9aa88d094e82c318f8c7312450ec970592caf506a62b392b47e3f0f35380be5be9d5
+  metadata.gz: 4c456c2e5ff0b55a6d51bc777770bed926b6cfa4c8a1393fda110f5d0a8d3e0e49af5c5399e1a0bdf2f4c8f5632e19ec8490975722842a5657b9f6e737c4412a
+  data.tar.gz: 5ff47c4204e58ad1e49bd48cd146d4f51ccf44254f1244530b0fd39f8fa2b5817531cfa293409a3f6fbad7063bc3425599e2c1bf37d094b5dbb45bba5cc13dc8

data/CHANGELOG.md

@@ -1,6 +1,38 @@
 # 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
+
+### Changed
+- Text extraction cache keys now include the source digest, extraction configuration, Plaintext version, and cache schema version so configuration or extractor changes invalidate stale results
+- Extracted document content now retains searchable metadata for title, category, file type, and date
+- Text cache cleanup now preserves shared digest files and removes orphaned files safely
+- Text extraction now enforces `text_max_bytes` as a UTF-8 byte limit and closes source files after reading
+- PDF extraction now discovers `pdftotext` from `PATH`; added macOS and Debian/Ubuntu setup instructions and CI coverage with `poppler-utils`
+- Configured text cache directories are excluded from Jekyll output regardless of the `extract_text` setting
+- Rake packaging and test tasks no longer perform duplicate work and install only the current package artifact
+- Removed redundant package metadata and duplicate development dependency declarations
+
+### Fixed
+- Replaced use of the private ActiveSupport deprecation API with the public `ActiveSupport.deprecator` API
+- Empty extraction results now fall back to metadata-only searchable content
+- Manifest loading now validates entries, logs filesystem read failures, and resets dirty state after successful saves
+- Updated stale CI, development, cache-cleanup, and package-lock documentation
+
+### Tests
+- Added real PDF extraction coverage and stronger cache-hit/persistence assertions
+- Added tests for cache configuration invalidation, UTF-8 byte truncation, shared cache references, orphan cleanup, and conditional cache exclusion
 
 ## [0.6.0] - 2026-08-27
 

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
@@ -257,7 +281,7 @@ documents:
 - Cache invalidation uses **SHA-256 file digests** — only changed files
   are re-extracted
 - Stale cache entries for deleted files are cleaned up automatically
-  at the start of each build
+  at the end of each build
 - Falls back to metadata-only content (title, category, file type, date)
   if the `plaintext` gem is missing or extraction fails
 
@@ -287,6 +311,20 @@ tools needed). PDF extraction shells out to a system command:
 | DOCX/PPTX/XLSX | rubyzip (Ruby gem, no CLI needed) |
 | ODT/ODS/ODP | rubyzip (Ruby gem, no CLI needed) |
 
+Install `pdftotext` for PDF extraction:
+
+```bash
+# macOS
+brew install poppler
+
+# Debian/Ubuntu
+sudo apt-get install poppler-utils
+```
+
+On macOS and other non-standard installations, the executable is discovered
+from `PATH`. You can also configure a custom `pdftotext` command through the
+`plaintext` gem configuration.
+
 ## Development
 
 ```bash

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

@@ -28,6 +28,7 @@ module Jekyll
       def generate(site)
         @site   = site
         @config = Configuration.read(site)
+        @text_manifest = nil
 
         root = File.join(site.source, @config["root"])
         unless Dir.exist?(root)
@@ -36,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"]
@@ -60,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
@@ -128,18 +132,19 @@ module Jekyll
         manifest = text_manifest
         rel_path = info[:rel_path]
         digest = ::Digest::SHA256.file(info[:path]).hexdigest
+        metadata = extraction_cache_metadata
 
-        cached = manifest.get(rel_path, digest)
+        cached = manifest.get(rel_path, digest, metadata)
         return cached if cached
 
-        # Suppress ActiveSupport deprecation warnings from the plaintext gem
-        # (it uses String#mb_chars, deprecated in Rails 8.2).
-        # We apply our own truncation below, so the gem's internal limit is redundant.
-        text = ActiveSupport::Deprecation._instance.silence do
-          ::Plaintext::Resolver.new(File.open(info[:path]), content_type).text
+        configure_pdf_extractor(content_type)
+        text = ActiveSupport.deprecator.silence do
+          File.open(info[:path], "rb") do |file|
+            ::Plaintext::Resolver.new(file, content_type).text
+          end
         end
-        text = text&.truncate(@config["text_max_bytes"]) if text
-        manifest.set(rel_path, digest, text) if text
+        text = truncate_bytes(text, @config["text_max_bytes"]) if text
+        manifest.set(rel_path, digest, text, metadata) if text
         text
       rescue StandardError => e
         ::Jekyll.logger.warn "jekyll-documents",
@@ -147,6 +152,19 @@ module Jekyll
         nil
       end
 
+      def configure_pdf_extractor(content_type)
+        return unless content_type == "application/pdf"
+        return unless ::Plaintext::Configuration["pdftotext"].nil?
+
+        executable = ENV.fetch("PATH", "").split(File::PATH_SEPARATOR)
+                        .map { |directory| File.join(directory, "pdftotext") }
+                        .find { |path| File.executable?(path) }
+        return unless executable
+
+        ::Plaintext::Configuration.config["pdftotext"] =
+          [executable, "-enc", "UTF-8", "__FILE__", "-"]
+      end
+
       def load_plaintext
         return true if defined?(::Plaintext)
 
@@ -163,6 +181,26 @@ module Jekyll
         @text_manifest ||= TextExtractionManifest.new(@site, @config["text_cache_dir"])
       end
 
+      def extraction_cache_metadata
+        {
+          "schema_version" => 1,
+          "text_max_bytes" => @config["text_max_bytes"],
+          "plaintext_version" => if ::Plaintext.const_defined?(:VERSION)
+                                   ::Plaintext::VERSION.to_s
+                                 else
+                                   "unknown"
+                                 end
+        }
+      end
+
+      def truncate_bytes(text, max_bytes)
+        bytes = text.to_s.encode("UTF-8", invalid: :replace, undef: :replace)
+                    .byteslice(0, max_bytes)
+        bytes = bytes.to_s.force_encoding("UTF-8")
+        bytes = bytes.byteslice(0, bytes.bytesize - 1) until bytes.valid_encoding?
+        bytes
+      end
+
       def cleanup_manifest(current_rel_paths)
         text_manifest.cleanup_deleted(current_rel_paths)
         text_manifest.save
@@ -170,37 +208,40 @@ 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"]
-                        extract_file_content(info) || searchable_content(info[:title], data,
-                                                                         info[:file_type])
+                        extracted_content = extract_file_content(info)
+                        if extracted_content && !extracted_content.empty?
+                          "#{metadata_content} #{extracted_content}"
+                        else
+                          metadata_content
+                        end
                       else
-                        searchable_content(info[:title], data, info[:file_type])
+                        metadata_content
                       end
       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
@@ -209,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
@@ -243,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",
@@ -252,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/layout_registrar.rb

@@ -60,7 +60,7 @@ Jekyll::Hooks.register :site, :after_init do |site|
 
   # Exclude the text extraction cache directory from Jekyll output
   config = Jekyll::Documents::Configuration.read(site)
-  if config["extract_text"] && config["text_cache_dir"]
+  if config["text_cache_dir"]
     site.config["exclude"] = Array(site.config["exclude"])
     unless site.config["exclude"].include?(config["text_cache_dir"])
       site.config["exclude"] << config["text_cache_dir"]

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/text_extraction_manifest.rb

@@ -6,6 +6,61 @@ require "digest"
 
 module Jekyll
   module Documents
+    module TextExtractionManifestSupport
+      private
+
+      def load_manifest
+        return {} unless File.file?(@manifest_path)
+
+        data = JSON.parse(File.read(@manifest_path, encoding: "UTF-8"))
+        data.is_a?(Hash) ? data.select { |_path, entry| valid_entry?(entry) } : {}
+      rescue JSON::ParserError => e
+        ::Jekyll.logger.warn "jekyll-documents",
+                             "Corrupt text extraction manifest, starting fresh: #{e.message}"
+        {}
+      rescue StandardError => e
+        ::Jekyll.logger.warn "jekyll-documents",
+                             "Text extraction manifest read failed: #{e.message}"
+        {}
+      end
+
+      def valid_entry?(entry)
+        entry.is_a?(Hash) && entry.values_at("digest", "cache_key", "text_file").all?(String)
+      end
+
+      def cache_key(digest, metadata)
+        Digest::SHA256.hexdigest(JSON.generate("digest" => digest, "metadata" => metadata))
+      end
+
+      def text_file_path(text_file)
+        return unless text_file.is_a?(String)
+
+        path = File.expand_path(File.join(@text_dir, text_file))
+        root = File.expand_path(@text_dir)
+        path.start_with?("#{root}#{File::SEPARATOR}") ? path : nil
+      end
+
+      def write_text_file(digest, text)
+        shard = digest[0, 2]
+        subdir = File.join(@text_dir, shard)
+        FileUtils.mkdir_p(subdir)
+        filename = "#{digest}.txt"
+        File.write(File.join(subdir, filename), text, encoding: "UTF-8")
+        File.join(shard, filename)
+      end
+
+      def cleanup_unreferenced_text_files
+        referenced = @manifest.values.filter_map do |entry|
+          text_file_path(entry["text_file"]) if valid_entry?(entry)
+        end.to_set
+        Dir.glob(File.join(@text_dir, "**", "*.txt")).each do |path|
+          File.delete(path) unless referenced.include?(File.expand_path(path))
+        end
+      rescue StandardError
+        nil
+      end
+    end
+
     # Manages the text extraction manifest — a persistent JSON file that tracks
     # which documents have had their text extracted, keyed by SHA-256 digest.
     #
@@ -19,6 +74,8 @@ module Jekyll
     # - Cleanup of entries for deleted source files
     # - Survives `jekyll clean` (stored in site source, not .jekyll-cache/)
     class TextExtractionManifest
+      include TextExtractionManifestSupport
+
       MANIFEST_FILENAME = "text-extraction-manifest.json"
       TEXT_SUBDIR = "text"
 
@@ -40,13 +97,13 @@ module Jekyll
       # @param rel_path [String] relative path of the source document
       # @param digest [String] SHA-256 hex digest of the source file
       # @return [String, nil] extracted text if cache hit, nil otherwise
-      def get(rel_path, digest)
+      def get(rel_path, digest, metadata = {})
         entry = @manifest[rel_path]
-        return nil unless entry
-        return nil unless entry["digest"] == digest
+        return nil unless valid_entry?(entry)
+        return nil unless entry["cache_key"] == cache_key(digest, metadata)
 
         text_file = text_file_path(entry["text_file"])
-        return nil unless File.file?(text_file)
+        return nil unless text_file && File.file?(text_file)
 
         File.read(text_file, encoding: "UTF-8")
       rescue StandardError => e
@@ -60,13 +117,15 @@ module Jekyll
       # @param digest [String] SHA-256 hex digest of the source file
       # @param text [String] the extracted text
       # @return [void]
-      def set(rel_path, digest, text)
+      def set(rel_path, digest, text, metadata = {})
         text_file = write_text_file(digest, text)
         @manifest[rel_path] = {
           "digest" => digest,
+          "cache_key" => cache_key(digest, metadata),
           "text_file" => text_file,
           "extracted_at" => Time.now.to_i
         }
+        cleanup_unreferenced_text_files
         @dirty = true
       end
 
@@ -81,12 +140,11 @@ module Jekyll
         @manifest.each_key do |rel_path|
           next if current_set.include?(rel_path)
 
-          entry = @manifest[rel_path]
-          delete_text_file(entry["text_file"]) if entry
           @manifest.delete(rel_path)
           removed += 1
           @dirty = true
         end
+        cleanup_unreferenced_text_files
 
         removed
       end
@@ -98,7 +156,10 @@ module Jekyll
         return unless @dirty
 
         content = JSON.pretty_generate(@manifest)
-        return if File.exist?(@manifest_path) && File.binread(@manifest_path) == content
+        if File.exist?(@manifest_path) && File.binread(@manifest_path) == content
+          @dirty = false
+          return
+        end
 
         FileUtils.mkdir_p(@cache_root)
         temporary_path = "#{@manifest_path}.tmp-#{Process.pid}-#{Thread.current.object_id}"
@@ -108,6 +169,7 @@ module Jekyll
           file.fsync
         end
         File.rename(temporary_path, @manifest_path)
+        @dirty = false
       ensure
         FileUtils.rm_f(temporary_path) if defined?(temporary_path) && temporary_path
       end
@@ -116,9 +178,9 @@ module Jekyll
       # @param rel_path [String] relative path of the source document
       # @param digest [String] SHA-256 hex digest of the source file
       # @return [Boolean]
-      def cached?(rel_path, digest)
+      def cached?(rel_path, digest, metadata = {})
         entry = @manifest[rel_path]
-        !!(entry && entry["digest"] == digest)
+        !!(valid_entry?(entry) && entry["cache_key"] == cache_key(digest, metadata))
       end
 
       # Number of entries in the manifest.
@@ -126,44 +188,6 @@ module Jekyll
       def size
         @manifest.size
       end
-
-      private
-
-      def load_manifest
-        return {} unless File.file?(@manifest_path)
-
-        data = JSON.parse(File.read(@manifest_path, encoding: "UTF-8"))
-        data.is_a?(Hash) ? data : {}
-      rescue JSON::ParserError => e
-        ::Jekyll.logger.warn "jekyll-documents",
-                             "Corrupt text extraction manifest, starting fresh: #{e.message}"
-        {}
-      rescue StandardError
-        {}
-      end
-
-      def text_file_path(text_file)
-        File.join(@text_dir, text_file)
-      end
-
-      def write_text_file(digest, text)
-        shard = digest[0, 2]
-        subdir = File.join(@text_dir, shard)
-        FileUtils.mkdir_p(subdir)
-        filename = "#{digest}.txt"
-        path = File.join(subdir, filename)
-        File.write(path, text, encoding: "UTF-8")
-        File.join(shard, filename)
-      end
-
-      def delete_text_file(text_file)
-        return unless text_file
-
-        path = text_file_path(text_file)
-        File.delete(path) if File.file?(path)
-      rescue StandardError
-        nil
-      end
     end
   end
 end

data/lib/jekyll/documents/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Documents
-    VERSION = "0.6.0"
+    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.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Svend Gundestrup