jekyll-documents 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c05b94feef92602870b24fd7b9c4e9244eb724061c1ef599ed12a23905d51ad
-  data.tar.gz: ccfe08306d471478e21092fd7518df1c6d593b05fa219051a6d866d3c947c6c9
+  metadata.gz: b2e673dc309679ea3bc1ce25687bb9fbf52901f27b7b29517c63ef9337291e82
+  data.tar.gz: f89cef0e3d22c85665b516bd52da7f137b612c62c21f24e22ef33dc7a10170a8
 SHA512:
-  metadata.gz: '087a677f0f1efd8c54d7b52c05c1fd0b88c746e9063f8fc0ba843c5ca24db53b8cbdd6904a959d7ca606e490bf8da590ff9b400b21a9de25204079ed0f0b0eff'
-  data.tar.gz: 7519b8f1e7035b4391299dd6399dcb1a6fa6572d4b3567891e35fc3f383a7b2958acc28bdbfe058983d6fbf73592c33a609dd07ae082751410873d8d29ac1434
+  metadata.gz: 956c33415793dd9e285f9e81874b612278c188d0dd39237a1bbdeea7964af1d784655b171d7efbf485b37dfa948c02ade3703b4e82e1b411a90d9c2049cb0f65
+  data.tar.gz: c6069125baef1f06acbd58124f5993881b2e595a60b02e470fb0a8a3a94a764f62b0bbd8ad53320b325d614590aa494fb469f83674145f1924db945e1afc0e46

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [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

data/lib/jekyll/documents/generator.rb

@@ -65,6 +65,7 @@ module Jekyll
           data["file_type"]  = file_type
           data["icon_set"]   = icon_set
           data["icon_url"]   = Jekyll::Documents::FileTypeIcons.icon_for(file_type, icon_set)
+          data["file_size"]  = File.size(path)
           data["slug"]       = slug
           data["permalink"]  = @config["permalink"]
                                .gsub(":category", data["category"].to_s)

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.3.3"
   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,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-documents
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Svend Gundestrup
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -266,6 +266,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