jekyll-agent-markdown 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b29b2ab68b394cfc7b37489422cbb516b6f4c3dce9af32aeb459438fce2b41ee
-  data.tar.gz: ce818d0127fcaf5cb89788144a32795264c962406219db55360fedf3bfb253b0
+  metadata.gz: 747268dbb22f5d319ed8f760fa97ff9503eb12b632a44c8ef74bcef8694d821d
+  data.tar.gz: 57e5b25acc73b618d1d74f3e11f8e20f44393af1f976bfd17669e2f6d52b226a
 SHA512:
-  metadata.gz: ee88b5e526b873e40eaa405c99810de61431aabbbf43bff1c8705e6e17ed828df408d94581735dcfed3180b10cf3e04116c8a6c216297fbb89c1cffab6521f45
-  data.tar.gz: 29c1aaaa685a8c8a44c9ffb7041a0f9c05e9cf1043ebd70aab445a3b5cfc634b0539d2941f56839ed07cb5ce57209657fe708df1f2ecfc0cb170d284f8c0046a
+  metadata.gz: 02e6fa6d6a722bee4b94052f2a2d42ea0d5de18599f4380da778c1e42390a7b54e346d68e3830b7cb0bbb35c0634031ae4fac1c2d8374c074947191f38248cb6
+  data.tar.gz: 715edcbd124b53fca22dedfbf96e115fc4ed1373797ef27ded43868c551f5ec61aecabc1f8057612a842f237d9a544c20e228ecd9ec33a3899d0c308854fb11c

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-20
+
+- Add configurable `llms.txt` ordering by normalized published date, defaulting to newest first and placing missing or invalid dates last.
+- Include available published and updated dates in `llms.txt` and Markdown exports by default, with an `include_dates` opt-out.
+
 ## [0.1.0] - 2026-08-18
 
 - Export Jekyll posts as raw Markdown siblings.

data/README.md

@@ -27,9 +27,11 @@ Both exports are enabled by default:
 agent_markdown:
   posts: true
   llms_txt: true
+  sort: desc
+  include_dates: true
 ```
 
-`posts` and `llms_txt` are the only accepted settings. Each accepts `true`, `false`, or one of the false-style strings `"false"`, `"no"`, and `"off"` (case-insensitively). Unknown keys and other values stop the build with a configuration error instead of being silently ignored. An explicit per-post `agent_markdown` value follows the same rules, so a mistyped opt-out cannot publish raw source by accident.
+`posts`, `llms_txt`, and `include_dates` accept `true`, `false`, or one of the false-style strings `"false"`, `"no"`, and `"off"` (case-insensitively). `sort` accepts `asc` or `desc` and defaults to `desc`, ordering the `llms.txt` article list by normalized published date. Posts with a missing, incomplete, or invalid published date are listed last in their existing order. Unknown keys and other values stop the build with a configuration error instead of being silently ignored. An explicit per-post `agent_markdown` value follows the boolean-setting rules, so a mistyped opt-out cannot publish raw source by accident.
 
 Set `url` to your site's absolute HTTP(S) URL; the `llms.txt` index uses it to generate absolute article links:
 
@@ -54,7 +56,16 @@ Markdown sibling paths are deterministic:
 
 Extensions are matched case-insensitively, and percent-encoded aliases are compared by their final decoded destination. Destination ownership also treats case-only and Unicode-normalization aliases as equivalent on every platform, keeping builds portable across filesystems. File-versus-directory conflicts are reserved as well. Before adding an export, the plugin checks every page, static file, and writable collection document already known to Jekyll. The existing destination owner wins; later post exports are skipped with a warning and omitted from `llms.txt`. A committed `llms.txt` wins in the same way.
 
-The generated file contains the post's original Markdown body with no front matter, HTML conversion, or Liquid rendering. Liquid tags and directives such as `{{ site.title }}` are published literally. Exclude one post with front matter:
+The generated file preserves the post's original Markdown body as its initial content, with no front matter, HTML conversion, or Liquid rendering. Liquid tags and directives such as `{{ site.title }}` are published literally. By default, the plugin appends the post's published `date` and optional `last_modified_at` value as a small footer:
+
+```text
+---
+Published at: 2026-01-01 | Updated at: 2026-02-03
+```
+
+Each available date is formatted as `YYYY-MM-DD`. String values must contain an explicit year, month, and day; missing, incomplete, and invalid values and their labels are omitted. An empty post contains only the metadata line, without a leading `---` that could be mistaken for front matter. Set `include_dates: false` to omit date metadata from both Markdown exports and `llms.txt`, leaving the body-only export shape used before date metadata was introduced.
+
+Exclude one post with front matter:
 
 ```yaml
 agent_markdown: false
@@ -81,7 +92,7 @@ The generated `/llms.txt` is a compact index, for example:
 
 > Posts only. Pages and collections are not included.
 
-- [First article](https://example.com/articles/first.md)
+- [First article](https://example.com/articles/first.md) | Published at: 2026-01-01
 ```
 
 ## Deployment notes
@@ -90,7 +101,7 @@ Configure your host to serve generated `.md` files as `Content-Type: text/markdo
 
 ## v0.1.0 limitations
 
-Only posts are exported. Pages and custom collections, custom Markdown transformations or templates, front-matter allowlisting, automatic response headers, sitemaps, and AI-specific metadata are intentionally deferred.
+Only posts are exported. Pages and custom collections, custom Markdown transformations or templates, front-matter allowlisting, automatic response headers, sitemaps, and richer article metadata are intentionally deferred.
 
 ## Development
 

data/lib/jekyll/agent_markdown/configuration.rb

@@ -6,8 +6,9 @@ require "uri"
 module Jekyll
   module AgentMarkdown
     class Configuration
-      ALLOWED_SETTINGS = %w[llms_txt posts].freeze
+      ALLOWED_SETTINGS = %w[include_dates llms_txt posts sort].freeze
       FALSE_STRINGS = %w[false no off].freeze
+      SORT_ORDERS = %w[asc desc].freeze
 
       class << self
         def for(site)
@@ -26,6 +27,10 @@ module Jekyll
           !disabled?(settings.fetch(key, true))
         end
 
+        def sort_order(settings)
+          settings.fetch("sort", "desc")
+        end
+
         def enabled_value?(value, name:)
           validate_value!(name, value)
           !disabled?(value)
@@ -66,10 +71,21 @@ module Jekyll
 
         def validate_values!(settings)
           settings.each do |key, value|
-            validate_value!("agent_markdown.#{key}", value)
+            if key == "sort"
+              validate_sort_order!(value)
+            else
+              validate_value!("agent_markdown.#{key}", value)
+            end
           end
         end
 
+        def validate_sort_order!(value)
+          return if SORT_ORDERS.include?(value)
+
+          raise Jekyll::Errors::FatalException,
+                "agent_markdown.sort must be asc or desc; got #{value.inspect}"
+        end
+
         def validate_value!(name, value)
           return if valid_value?(value)
 

data/lib/jekyll/agent_markdown/date_metadata.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Jekyll
+  module AgentMarkdown
+    class DateMetadata
+      DATE_FORMAT = "%Y-%m-%d"
+      FIELDS = {
+        "Published at" => "date",
+        "Updated at" => "last_modified_at"
+      }.freeze
+      REQUIRED_DATE_PARTS = %i[year mon mday].freeze
+
+      def initialize(data)
+        @data = data
+      end
+
+      def to_s
+        @to_s ||= FIELDS.filter_map { |label, key| entry(label, @data[key]) }.join(" | ")
+      end
+
+      def append_to(content)
+        return content if to_s.empty?
+        return "#{self}\n" if content.empty?
+
+        "#{content}#{separator_for(content)}---\n#{self}\n"
+      end
+
+      def published_date = parsed_date(@data["date"])
+
+      private
+
+      def entry(label, value)
+        date = formatted_date(value)
+        "#{label}: #{date}" if date
+      end
+
+      def separator_for(content)
+        content.end_with?("\n") ? "\n" : "\n\n"
+      end
+
+      def formatted_date(value)
+        parsed_date(value)&.strftime(DATE_FORMAT)
+      end
+
+      def parsed_date(value)
+        return Date.strptime(value.strftime(DATE_FORMAT), DATE_FORMAT) if value.respond_to?(:strftime)
+        return unless value.is_a?(String)
+
+        parts = Date._parse(value, false)
+        return unless REQUIRED_DATE_PARTS.all? { |part| parts.key?(part) }
+
+        Date.new(*parts.values_at(*REQUIRED_DATE_PARTS))
+      rescue Date::Error
+        nil
+      end
+    end
+  end
+end

data/lib/jekyll/agent_markdown/generator.rb

@@ -2,6 +2,7 @@
 
 require "jekyll"
 require_relative "configuration"
+require_relative "date_metadata"
 require_relative "destination_claims"
 require_relative "markdown_sibling_path"
 require_relative "raw_markdown_file"
@@ -24,7 +25,7 @@ module Jekyll
 
         @context = Liquid::Context.new({}, {}, { site: site })
         destination_claims = destination_claims(site)
-        included_posts = export_posts(site, destination_claims) if Configuration.enabled?(settings, "posts")
+        included_posts = export_posts(site, settings, destination_claims) if Configuration.enabled?(settings, "posts")
         write_llms_txt(site, settings, included_posts || [], destination_claims)
       end
 
@@ -36,16 +37,16 @@ module Jekyll
         end
       end
 
-      def export_posts(site, destination_claims)
-        site.posts.docs.filter_map { |post| export_post(site, destination_claims, post) }
+      def export_posts(site, settings, destination_claims)
+        site.posts.docs.filter_map { |post| export_post(site, settings, destination_claims, post) }
       end
 
-      def export_post(site, destination_claims, post)
+      def export_post(site, settings, destination_claims, post)
         setting = post.data.fetch("agent_markdown", true)
         setting_name = "agent_markdown in #{post.relative_path}"
         return unless Configuration.enabled_value?(setting, name: setting_name)
 
-        file = RawMarkdownFile.new(site, MarkdownSiblingPath.for(post.url), post.content)
+        file = RawMarkdownFile.new(site, MarkdownSiblingPath.for(post.url), post_content(post, settings))
         url = file.url
         return collision_warning(post, url) unless claim_destination?(destination_claims, site, file)
 
@@ -64,15 +65,13 @@ module Jekyll
         return unless Configuration.enabled?(settings, "llms_txt")
         return unless llms_txt_ready?(site, settings)
 
-        file = RawMarkdownFile.new(site, "/llms.txt", llms_txt(site, posts))
+        file = RawMarkdownFile.new(site, "/llms.txt", llms_txt(site, posts, settings))
         return llms_txt_collision_warning unless claim_destination?(destination_claims, site, file)
 
         site.static_files << file
       end
 
-      def claim_destination?(destination_claims, site, file)
-        destination_claims.claim?(file.destination(site.dest))
-      end
+      def claim_destination?(destination_claims, site, file) = destination_claims.claim?(file.destination(site.dest))
 
       def llms_txt_collision_warning
         Jekyll.logger.warn "AgentMarkdown:",
@@ -91,8 +90,8 @@ module Jekyll
         false
       end
 
-      def llms_txt(site, posts)
-        sections = [llms_headings(site), article_links(site, posts)]
+      def llms_txt(site, posts, settings)
+        sections = [llms_headings(site), article_links(site, posts, settings)]
         "#{sections.reject(&:empty?).join("\n\n")}\n"
       end
 
@@ -106,22 +105,36 @@ module Jekyll
         headings.join("\n\n")
       end
 
-      def one_line(value)
-        return "" if value.nil? || value == false
+      def one_line(value) = value ? value.to_s.gsub(/\s+/, " ").strip : ""
 
-        value.to_s.gsub(/\s+/, " ").strip
+      def article_links(site, posts, settings)
+        site_url = site.config["url"].sub(%r{/+\z}, "")
+        sorted_posts(posts, settings).map { |post| article_link(site_url, post, settings) }.join("\n")
       end
 
-      def article_links(site, posts)
-        site_url = site.config["url"].sub(%r{/+\z}, "")
-        posts.map { |post| article_link(site_url, post) }.join("\n")
+      def sorted_posts(posts, settings)
+        dated, undated = posts.map { |post| [post, date_metadata(post).published_date] }.partition(&:last)
+        dated.sort_by!(&:last)
+        dated.reverse! if Configuration.sort_order(settings) == "desc"
+        (dated + undated).map(&:first)
       end
 
-      def article_link(site_url, post)
+      def article_link(site_url, post, settings)
         url = "#{site_url}#{relative_url(post.data.fetch("agent_markdown_url"))}"
-        "- [#{link_title(post)}](#{escaped_link_url(url)})"
+        link = "- [#{link_title(post)}](#{escaped_link_url(url)})"
+        return link unless Configuration.enabled?(settings, "include_dates")
+
+        [link, date_metadata(post).to_s].reject(&:empty?).join(" | ")
       end
 
+      def post_content(post, settings)
+        return post.content unless Configuration.enabled?(settings, "include_dates")
+
+        date_metadata(post).append_to(post.content)
+      end
+
+      def date_metadata(post) = DateMetadata.new(post.data)
+
       # Backslashes and square brackets would end the Markdown link text early;
       # whitespace runs (including newlines) would break the one-entry-per-line
       # format.
@@ -132,9 +145,7 @@ module Jekyll
       end
 
       # Unescaped parentheses would end the Markdown link destination early.
-      def escaped_link_url(url)
-        url.gsub("(", "%28").gsub(")", "%29")
-      end
+      def escaped_link_url(url) = url.gsub("(", "%28").gsub(")", "%29")
     end
   end
 end

data/lib/jekyll/agent_markdown/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module AgentMarkdown
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-agent-markdown
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Lucian Ghinda
@@ -42,6 +42,7 @@ files:
 - README.md
 - lib/jekyll-agent-markdown.rb
 - lib/jekyll/agent_markdown/configuration.rb
+- lib/jekyll/agent_markdown/date_metadata.rb
 - lib/jekyll/agent_markdown/destination_claims.rb
 - lib/jekyll/agent_markdown/generator.rb
 - lib/jekyll/agent_markdown/markdown_sibling_path.rb