jekyll-documents 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c05b94feef92602870b24fd7b9c4e9244eb724061c1ef599ed12a23905d51ad
-  data.tar.gz: ccfe08306d471478e21092fd7518df1c6d593b05fa219051a6d866d3c947c6c9
+  metadata.gz: 76640be0741d32137905f8281bc4e83e4e895971a9ad39e7f360bccf06ba5eef
+  data.tar.gz: 93ac35f0606b84b474ef6aff260e21c7dab78ce5e4a8f7f80b4b97493755ae8d
 SHA512:
-  metadata.gz: '087a677f0f1efd8c54d7b52c05c1fd0b88c746e9063f8fc0ba843c5ca24db53b8cbdd6904a959d7ca606e490bf8da590ff9b400b21a9de25204079ed0f0b0eff'
-  data.tar.gz: 7519b8f1e7035b4391299dd6399dcb1a6fa6572d4b3567891e35fc3f383a7b2958acc28bdbfe058983d6fbf73592c33a609dd07ae082751410873d8d29ac1434
+  metadata.gz: db8fa1ad5fd90e910238d8b3b41427d8eeb8451ba70ca095cd610e26b56db88ae564e32856b6890c8c1e8af7b4a294fa8a9a9e7219fdd157bc7b0d80aa0c4181
+  data.tar.gz: a19a1da88694fd8282f3040a3bdad01ca5627667a116a984d16d916a875a346bb156bb371374b6b0ae241b6cbe2a97c8ecfc8cb40a1728960243ce1359e60e97

data/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-26
+
+### Added
+- `categories` array baked into each document's data (in addition to the existing singular `category`) for compatibility with search plugins like `jekyll-client-search` that expect the plural Jekyll convention
+- Searchable content string (title, category, file type, date) set as document content so client-side search engines can index uploaded documents
+
+### Changed
+- Refactored `Generator#generate` by extracting `bake_document_data` and `searchable_content` helper methods to keep method length within RuboCop limits
+
+### Changed
+- Simplified release workflow to tag-push trigger (`push: tags: v*`) — no manual `gh release create` needed
+- Switched to RubyGems trusted publishing (`rubygems/release-gem@v1` with OIDC)
+- Centralized version in `version.rb` as single source of truth — removed `version` field from `package.json` (was drifted to 0.3.1)
+- Added `rake version:bump` and `rake version:check_changelog` tasks
+- Added CHANGELOG gate to release workflow (fails if entry missing for the version)
+- Added `npm audit` and `npm outdated` (non-blocking) to CI
+- Replaced `setup_hooks.sh` with `bin/install-hooks.sh` (pre-commit: rubocop only, pre-push: rubocop + rspec)
+- Dropped reek from gemspec, Rakefile, and deleted `.reek.yml` (KISS)
+- Deleted `bump_version.sh`, `release.sh`, `rollback.sh` — replaced by rake tasks and release workflow
+- Renamed `AI_INSTRUCTIONS.md` to `AGENTS.md` (agents.md open convention)
+- Updated `CLAUDE.md` and `.windsurfrules` to point to `AGENTS.md`
+
+## [0.3.3] - 2026-08-12
+
+### Added
+- `{% doc_link "title" %}` Liquid tag for linking to documents by partial title or slug match (case-insensitive); renders file icon, title, and human-readable file size; supports `text:"custom label"`, `icon:false`, and `size:false` options
+- `{% doc_category "name" %}` Liquid tag for linking to category pages or listing documents by category; supports `text:"label"`, `list:true`, and `limit:N` options
+- `file_size` attribute baked into each document's data at generation time
+- `file_url` and `file_size` fields included in the generated `/documents.json` index
+- 30 RSpec examples covering `DocLinkTag` and `DocCategoryTag` (exact/partial matching, slug matching, icon/size rendering, custom text, baseurl, HTML escaping, list mode, limit, sorting, empty collection handling)
+
 ## [0.3.2] - 2026-08-12
 
 ### Added

data/README.md

@@ -74,12 +74,41 @@ The tag applies the configured icon set and site `baseurl` automatically. The `f
 
 ## Usage
 
+### Includes
+
 ```liquid
 {% include latest_documents.html count=5 %}
 {% include documents_list.html %}
 {% include documents_search.html %}
 ```
 
+### Liquid Tags
+
+**Link to a document** by title or slug (partial match, case-insensitive):
+
+```liquid
+{% doc_link "Annual Report" %}
+{% doc_link "annual" text:"Read the report" %}
+{% doc_link "board-meeting" icon:false size:false %}
+```
+
+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.
+
+**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 %}
+```
+
+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.
+
 ## Configuration
 
 ```yaml
@@ -110,8 +139,13 @@ See [README.Development.md](README.Development.md) for details.
 ## Release
 
 ```bash
-./bump_version.sh patch
-./release.sh
+bundle exec rake "version:bump[patch]"
+# Edit CHANGELOG.md
+git add lib/jekyll/documents/version.rb CHANGELOG.md
+git commit -m "Release X.Y.Z: summary"
+git tag -a vX.Y.Z -m "Release X.Y.Z"
+git push origin main
+git push origin vX.Y.Z
 ```
 
 ## License

data/jekyll-documents.gemspec

@@ -35,7 +35,6 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler-audit", "~> 0.9"
   spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "reek", "~> 6.5"
   spec.add_development_dependency "rspec", "~> 3.13"
   spec.add_development_dependency "rubocop", "~> 1.88"
   spec.add_development_dependency "rubocop-performance", "~> 1.26"

data/lib/jekyll/documents/generator.rb

@@ -55,23 +55,10 @@ module Jekyll
             collection: collection
           )
 
-          data = doc.data
-          data["layout"]     = @config["layout"]
-          data["title"]      = title
-          data["date"]       = date ? date.to_time : File.mtime(path)
-          data["category"]   = remap_category(category)
-          data["file_url"]   = "/#{rel_path}"
-          data["extension"]  = ext
-          data["file_type"]  = file_type
-          data["icon_set"]   = icon_set
-          data["icon_url"]   = Jekyll::Documents::FileTypeIcons.icon_for(file_type, icon_set)
-          data["slug"]       = slug
-          data["permalink"]  = @config["permalink"]
-                               .gsub(":category", data["category"].to_s)
-                               .gsub(":slug", slug)
-
-          doc.content = "Auto-generated document page."
-
+          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 }
+          bake_document_data(doc, file_info)
           collection.docs << doc
         end
       end
@@ -91,6 +78,33 @@ module Jekyll
         site.collections[label]
       end
 
+      def searchable_content(title, data, file_type)
+        date_str = data["date"].strftime("%Y-%m-%d")
+        "#{title} #{data['category']} #{file_type} #{date_str}"
+      end
+
+      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])
+        doc.content = searchable_content(info[:title], data, info[:file_type])
+      end
+
       # Creates a virtual source path for the document
       # @param basename [String] the file basename
       # @param category [String] the document category

data/lib/jekyll/documents/json_index_generator.rb

@@ -26,7 +26,9 @@ module Jekyll
             "slug" => data["slug"],
             "file_type" => data["file_type"],
             "extension" => data["extension"],
-            "icon_url" => data["icon_url"]
+            "icon_url" => data["icon_url"],
+            "file_url" => data["file_url"],
+            "file_size" => data["file_size"]
           }
         end
 

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Documents
+    class DocCategoryTag < Liquid::Tag
+      public_class_method :new
+
+      include Jekyll::Filters::URLFilters
+
+      def initialize(tag_name, markup, tokens)
+        super
+        @category, @options = parse_markup(markup)
+      end
+
+      def render(context)
+        docs = documents_from(context)
+        return "" if docs.empty?
+
+        categories = available_categories(docs)
+        category = resolve_category(@category, categories)
+        return "" unless category
+
+        @context = context
+        return render_list(docs, category) if @options["list"] == "true"
+
+        render_link(category)
+      end
+
+      private
+
+      def documents_from(context)
+        site = context.registers[:site]
+        site.collections["documents"]&.docs || []
+      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) }
+      end
+
+      def render_link(category)
+        url = relative_url("/documents/#{category}/")
+        text = @options["text"] || category
+        %(<a href="#{escape_html(url)}">#{escape_html(text)}</a>)
+      end
+
+      def render_list(docs, category)
+        cat_docs = sorted_category_docs(docs, category)
+        limit = @options["limit"]&.to_i
+        cat_docs = cat_docs.first(limit) if limit&.positive?
+
+        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
+      end
+
+      def list_items(cat_docs)
+        cat_docs.each_with_object(+"") do |doc, out|
+          title = escape_html(doc.data["title"])
+          url = escape_html(relative_url(doc.url))
+          date = (doc.data["date"] || Time.at(0)).strftime("%Y-%m-%d")
+          out << %(<li><a href="#{url}">#{title}</a> <small>(#{date})</small></li>\n)
+        end
+      end
+
+      def parse_markup(markup)
+        text = markup.to_s
+        category, remainder = extract_category(text)
+        options = extract_options(remainder)
+        [category, options]
+      end
+
+      def extract_category(text)
+        quoted = text.match(/\A["']([^"']+)["']/)
+        return [quoted[1], text[quoted.end(0)..]] if quoted
+
+        bare = text.strip.match(/\A([^\s]+)/)
+        return [nil, ""] unless bare
+
+        [bare[1], text[bare.end(0)..]]
+      end
+
+      def extract_options(text)
+        options = {}
+        text.to_s.scan(
+          /(\w+)\s*:\s*(?:'([^']*)'|"([^"]*)"|([^\s]+))/
+        ) do |key, single, double, bare|
+          options[key] = single || double || bare
+        end
+        options
+      end
+
+      def escape_html(value)
+        value.to_s.gsub(/[&<>"']/,
+                        "&" => "&amp;",
+                        "<" => "&lt;",
+                        ">" => "&gt;",
+                        '"' => "&quot;",
+                        "'" => "&#39;")
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag("doc_category", Jekyll::Documents::DocCategoryTag)

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Documents
+    class DocLinkTag < Liquid::Tag
+      public_class_method :new
+
+      include Jekyll::Filters::URLFilters
+
+      SIZE_UNITS = %w[B KB MB GB].freeze
+
+      def initialize(tag_name, markup, tokens)
+        super
+        @query, @options = parse_markup(markup)
+      end
+
+      def render(context)
+        docs = documents_from(context)
+        return "" if docs.empty?
+
+        match = find_document(docs, @query)
+        return "" unless match
+
+        @context = context
+        url = relative_url(match.url)
+        text = @options["text"] || match.data["title"]
+
+        build_link(match, url, text)
+      end
+
+      private
+
+      def documents_from(context)
+        site = context.registers[:site]
+        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"
+        inner << %(<span class="doc-link-title">#{escape_html(text)}</span>)
+        inner << size_html(doc) if @options["size"] != "false"
+        %(<a href="#{escape_html(url)}" class="doc-link">#{inner}</a>)
+      end
+
+      def icon_html(doc)
+        icon_url = doc.data["icon_url"]
+        return "" unless icon_url
+
+        url = relative_url(icon_url)
+        file_type = doc.data["file_type"].to_s.upcase
+        "<img src=\"#{escape_html(url)}\" alt=\"#{file_type}\" class=\"file-icon doc-link-icon\" />"
+      end
+
+      def size_html(doc)
+        size = doc.data["file_size"]
+        return "" unless size
+
+        "<span class=\"doc-link-size has-text-grey is-size-7\">#{format_size(size)}</span>"
+      end
+
+      def format_size(bytes)
+        return "0 B" unless bytes&.positive?
+
+        value, unit = compute_size(bytes)
+        unit == "B" ? "#{value.to_i} B" : format("%<value>.1f %<unit>s", value:, unit:)
+      end
+
+      def compute_size(bytes)
+        value = bytes.to_f
+        SIZE_UNITS.each do |unit|
+          return [value, unit] if value < 1024 || unit == SIZE_UNITS.last
+
+          value /= 1024
+        end
+      end
+
+      def parse_markup(markup)
+        text = markup.to_s
+        query, remainder = extract_query(text)
+        options = extract_options(remainder)
+        [query, options]
+      end
+
+      def extract_query(text)
+        quoted = text.match(/\A["']([^"']+)["']/)
+        return [quoted[1], text[quoted.end(0)..]] if quoted
+
+        bare = text.strip.match(/\A([^\s]+)/)
+        return [nil, ""] unless bare
+
+        [bare[1], text[bare.end(0)..]]
+      end
+
+      def extract_options(text)
+        options = {}
+        text.to_s.scan(
+          /(\w+)\s*:\s*(?:'([^']*)'|"([^"]*)"|([^\s]+))/
+        ) do |key, single, double, bare|
+          options[key] = single || double || bare
+        end
+        options
+      end
+
+      def escape_html(value)
+        value.to_s.gsub(/[&<>"']/,
+                        "&" => "&amp;",
+                        "<" => "&lt;",
+                        ">" => "&gt;",
+                        '"' => "&quot;",
+                        "'" => "&#39;")
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag("doc_link", Jekyll::Documents::DocLinkTag)

data/lib/jekyll/documents/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Documents
-    VERSION = "0.3.2"
+    VERSION = "0.4.0"
   end
 end

data/lib/jekyll-documents.rb

@@ -14,6 +14,8 @@ require_relative "jekyll/documents/layout_registrar"
 # Liquid tag(s)
 require_relative "jekyll/documents/tags/latest_documents"
 require_relative "jekyll/documents/tags/document_icon"
+require_relative "jekyll/documents/tags/doc_link"
+require_relative "jekyll/documents/tags/doc_category"
 
 module Jekyll
   module Documents

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-documents
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Svend Gundestrup
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -58,20 +57,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: reek
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.5'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -266,6 +251,8 @@ files:
 - lib/jekyll/documents/generator.rb
 - lib/jekyll/documents/json_index_generator.rb
 - lib/jekyll/documents/layout_registrar.rb
+- lib/jekyll/documents/tags/doc_category.rb
+- lib/jekyll/documents/tags/doc_link.rb
 - lib/jekyll/documents/tags/document_icon.rb
 - lib/jekyll/documents/tags/latest_documents.rb
 - lib/jekyll/documents/utils.rb
@@ -280,7 +267,6 @@ metadata:
   documentation_uri: https://github.com/gundestrup/jekyll-documents
   homepage_uri: https://github.com/gundestrup/jekyll-documents
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -295,8 +281,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Auto-generate Jekyll pages for documents (PDF/DOCX/...) with category/date/title
   parsing.