jekyll-llms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 23293734537766446bec10323faae85e54243da602e80bca5d8675feffff8abd
+  data.tar.gz: 33b4069fbc9e69e04305f33f487788d67e279a2f60842d789400d7f43de87c20
+SHA512:
+  metadata.gz: a0e1ad5425441b17e99e316762b097c2f00f8b259cf4b9742ce9440d3712d740b51a160d95317459b94677dcd4fc3a1262e3e5642dba949394216c1af3a1101c
+  data.tar.gz: fac4f5e71fce6d09cfc476ac61fe236cfb00fa181d90be85eaa2cf0f17fbf0d62c9804ef11abfc36ae0618acc0b559ac7cc7b13331ed050a87b86b7d3e9ec758

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stanislav Katkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,59 @@
+# jekyll-llms
+
+Jekyll plugin that produces LLM-friendly formats alongside a regular website.
+
+Namely: `llms.txt`, Markdown sidecars, and HTML alternate links to sidecars.
+
+## Installation
+
+Add to `Gemfile` and run `bundle install`
+```ruby
+group :jekyll_plugins do
+  gem "jekyll-llms"
+end
+```
+
+Add to `_config` file:
+
+```yaml
+plugins:
+  - jekyll-llms
+```
+
+
+## Output
+
+- `/llms.txt`: Markdown index of included entries.
+- `*.md`: source-body sidecars for included entries.
+- HTML `<link rel="alternate" type="text/markdown" href="...">` tags pointing to sidecars.
+
+Sidecars are source bodies, not HTML-to-Markdown conversions. Front matter is removed. Liquid is rendered unless `render_with_liquid: false` is set.
+
+## Configuration
+
+```yaml
+llms:
+  markdown: true
+  llms_txt: true
+  include:
+    - pages
+    - posts
+  exclude:
+    - /404.html
+    - /assets/**
+```
+
+- `markdown`: generate sidecars, link `llms.txt` to sidecars, and add HTML alternate links. Default: `true`.
+- `llms_txt`: generate `/llms.txt`. Default: `true`.
+- `include`: `pages`, `posts`, and output collection names. Default: `[pages, posts]`.
+- `exclude`: URL, Markdown path, or source path globs. Default: `[]`.
+
+Per-entry opt-out:
+
+```yaml
+llms: false
+```
+
+## License
+
+MIT. See `LICENSE.txt`.

data/lib/jekyll/llms/config.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Llms
+    class Config
+      DEFAULTS = {
+        "markdown" => true,
+        "llms_txt" => true,
+        "include" => %w[pages posts],
+        "exclude" => [],
+      }.freeze
+
+      def self.from_site(site)
+        new(DEFAULTS.merge(site.config["llms"] || {}))
+      end
+
+      def initialize(values)
+        @values = values
+      end
+
+      def markdown?
+        @values.fetch("markdown")
+      end
+
+      def llms_txt?
+        @values.fetch("llms_txt")
+      end
+
+      def includes
+        @values.fetch("include")
+      end
+
+      def excludes
+        @values.fetch("exclude")
+      end
+    end
+  end
+end

data/lib/jekyll/llms/entry.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Llms
+    class Entry
+      attr_reader :item, :section, :url
+
+      def initialize(site:, item:, section:)
+        @item = item
+        @section = section
+        @url = Url.new(site: site, item: item)
+      end
+
+      def description
+        item.data.fetch("description", "").strip
+      end
+
+      def enabled?
+        item.data.fetch("llms", true)
+      end
+
+      def excluded_by?(patterns)
+        patterns.any? do |pattern|
+          url.matches?(pattern)
+        end
+      end
+
+      def title
+        title = item.data.fetch("title", "").strip
+        return title unless title.empty?
+
+        fallback_title
+      end
+
+      private
+
+      def fallback_title
+        if item.respond_to?(:basename_without_ext)
+          item.basename_without_ext
+        else
+          File.basename(item.name, ".*")
+        end
+      end
+
+    end
+  end
+end

data/lib/jekyll/llms/entry_set.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Llms
+    class EntrySet
+      def initialize(site:, config:)
+        @site = site
+        @config = config
+      end
+
+      def entries
+        config.includes.flat_map do |section|
+          section_entries(section)
+        end.select do |entry|
+          entry.enabled? && !entry.excluded_by?(config.excludes)
+        end.uniq do |entry|
+          entry.item.url
+        end
+      end
+
+      private
+
+      attr_reader :site, :config
+
+      def section_entries(section)
+        items_for(section).map do |item|
+          Entry.new(site: site, item: item, section: section)
+        end
+      end
+
+      def items_for(section)
+        case section
+        when "pages"
+          site.pages
+        when "posts"
+          site.posts.docs.sort { |a, b| b <=> a }
+        else
+          collection_items(section)
+        end
+      end
+
+      def collection_items(section)
+        collection = site.collections[section]
+        return [] unless collection&.write?
+
+        collection.docs
+      end
+    end
+  end
+end

data/lib/jekyll/llms/file_writer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Jekyll
+  module Llms
+    class FileWriter
+      def initialize(destination)
+        @destination = destination
+      end
+
+      def write(path, content)
+        full_path = File.join(destination, path)
+        FileUtils.mkdir_p(File.dirname(full_path))
+        File.write(full_path, content)
+      end
+
+      private
+
+      attr_reader :destination
+    end
+  end
+end

data/lib/jekyll/llms/html_linker.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Llms
+    class HtmlLinker
+      def initialize(site:, entries:)
+        @site = site
+        @entries = entries
+      end
+
+      def write
+        entries.each do |entry|
+          write_link(entry)
+        end
+      end
+
+      private
+
+      attr_reader :site, :entries
+
+      def write_link(entry)
+        path = entry.item.destination(site.dest)
+        return unless path.end_with?(".html")
+        return unless File.file?(path)
+
+        content = File.read(path)
+        File.write(path, content.sub("</head>", "#{link(entry)}\n</head>"))
+      end
+
+      def link(entry)
+        %(<link rel="alternate" type="text/markdown" href="#{entry.url.absolute(markdown: true)}">)
+      end
+    end
+  end
+end

data/lib/jekyll/llms/index.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Llms
+    class Index
+      def initialize(site:, entries:, markdown:)
+        @site = site
+        @entries = entries
+        @markdown = markdown
+      end
+
+      def content
+        content = "# #{title}\n\n"
+        content << "> #{description}\n" unless description.empty?
+
+        entries.group_by(&:section).each do |section, section_entries|
+          content << "\n## #{section_title(section)}\n\n"
+          section_entries.each do |entry|
+            content << "#{entry_line(entry)}\n"
+          end
+        end
+
+        content
+      end
+
+      private
+
+      attr_reader :site, :entries, :markdown
+
+      def title
+        site.config.fetch("title", "Jekyll Site")
+      end
+
+      def description
+        site.config.fetch("description", "").strip
+      end
+
+      def entry_line(entry)
+        line = "- [#{entry.title}](#{entry.url.absolute(markdown: markdown)})"
+        entry.description.empty? ? line : "#{line}: #{entry.description}"
+      end
+
+      def section_title(section)
+        section.split(/[_-]/).map(&:capitalize).join(" ")
+      end
+    end
+  end
+end

data/lib/jekyll/llms/markdown_source.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Llms
+    class MarkdownSource
+      def initialize(site:, item:)
+        @site = site
+        @item = item
+      end
+
+      def content
+        render_liquid(strip_frontmatter(read_file))
+      end
+
+      private
+
+      attr_reader :site, :item
+
+      def path
+        site.in_source_dir(item.relative_path)
+      end
+
+      def read_file
+        File.read(path)
+      end
+
+      def strip_frontmatter(content)
+        content =~ Document::YAML_FRONT_MATTER_REGEXP
+        Regexp.last_match.post_match
+      end
+
+      def render_liquid(content)
+        return content if item["render_with_liquid"] == false
+
+        Renderer.new(site, nil).render_liquid(content, payload, nil, path)
+      end
+
+      def payload
+        site.site_payload.tap do |payload|
+          payload["page"] = item
+        end
+      end
+
+    end
+  end
+end

data/lib/jekyll/llms/site_writer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Llms
+    class SiteWriter
+      def initialize(site)
+        @site = site
+        @config = Config.from_site(site)
+        @entries = EntrySet.new(site: site, config: config).entries
+        @files = FileWriter.new(site.dest)
+      end
+
+      def write
+        write_index if config.llms_txt?
+        if config.markdown?
+          write_markdown
+          write_html_links
+        end
+      end
+
+      private
+
+      attr_reader :site, :config, :entries, :files
+
+      def write_index
+        files.write("llms.txt", Index.new(site: site, entries: entries, markdown: config.markdown?).content)
+      end
+
+      def write_markdown
+        entries.each do |entry|
+          files.write(entry.url.markdown_path, MarkdownSource.new(site: site, item: entry.item).content)
+        end
+      end
+
+      def write_html_links
+        HtmlLinker.new(site: site, entries: entries).write
+      end
+    end
+  end
+end

data/lib/jekyll/llms/url.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Llms
+    class Url
+      MATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+      def initialize(site:, item:)
+        @site = site
+        @item = item
+      end
+
+      def absolute(markdown:)
+        "#{prefix}#{path(markdown: markdown)}"
+      end
+
+      def markdown_path
+        url = item.url
+        return "#{url}index.md" if url.end_with?("/")
+
+        File.join(File.dirname(url), "#{File.basename(url, ".*")}.md")
+      end
+
+      def matches?(pattern)
+        candidates.any? do |candidate|
+          glob_match?(pattern, candidate)
+        end
+      end
+
+      private
+
+      attr_reader :site, :item
+
+      def path(markdown:)
+        markdown ? markdown_path : item.url
+      end
+
+      def prefix
+        url, baseurl = site.config.fetch_values("url", "baseurl")
+
+        "#{url.delete_suffix("/")}#{baseurl.delete_suffix("/")}"
+      end
+
+      def candidates
+        [item.url, markdown_path, relative_source_path]
+      end
+
+      def relative_source_path
+        "/#{item.relative_path}"
+      end
+
+      def glob_match?(pattern, candidate)
+        File.fnmatch?(pattern.delete_prefix("/"), candidate.delete_prefix("/"), MATCH_FLAGS)
+      end
+    end
+  end
+end

data/lib/jekyll/llms/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Llms
+    VERSION = "0.1.0"
+  end
+end

data/lib/jekyll/llms.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "jekyll/llms/config"
+require "jekyll/llms/entry"
+require "jekyll/llms/entry_set"
+require "jekyll/llms/file_writer"
+require "jekyll/llms/html_linker"
+require "jekyll/llms/index"
+require "jekyll/llms/markdown_source"
+require "jekyll/llms/site_writer"
+require "jekyll/llms/url"
+require "jekyll/llms/version"
+
+module Jekyll
+  module Llms
+    class << self
+      def write(site)
+        SiteWriter.new(site).write
+      end
+    end
+  end
+end
+
+Jekyll::Hooks.register :site, :post_write do |site|
+  Jekyll::Llms.write(site)
+end

data/lib/jekyll-llms.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "jekyll/llms"

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-llms
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stanislav Katkov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: mutant
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: mutant-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Generates llms.txt and Markdown sidecars for Jekyll pages and posts.
+email:
+- git@skatkov.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/jekyll-llms.rb
+- lib/jekyll/llms.rb
+- lib/jekyll/llms/config.rb
+- lib/jekyll/llms/entry.rb
+- lib/jekyll/llms/entry_set.rb
+- lib/jekyll/llms/file_writer.rb
+- lib/jekyll/llms/html_linker.rb
+- lib/jekyll/llms/index.rb
+- lib/jekyll/llms/markdown_source.rb
+- lib/jekyll/llms/site_writer.rb
+- lib/jekyll/llms/url.rb
+- lib/jekyll/llms/version.rb
+homepage: https://github.com/skatkov/jekyll-llms
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/skatkov/jekyll-llms
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/skatkov/jekyll-llms
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Generate LLM-friendly files for Jekyll sites.
+test_files: []