jekyll-geo-kit 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 474d52c9e7b0c7dd088a685112ac2bd84a0e047e1c07991a648dc460620d4014
+  data.tar.gz: 4e3f157daadd1fc35543f485b908e66e60a2f913edb2d02350c15198cfbe9ea6
+SHA512:
+  metadata.gz: fe744eb153718d96d5da26b9502e3d735b03d232e84421cf1667ad27633e5f4acf168fcc68198d2f8d3d5e96b65953ff50e5ddaaefc3648713becc59ab70fd31
+  data.tar.gz: b228bc8d8bf9d8258cbb274fcbfc855aa4193824974b21cdb094729fb3645b752b1b4f248ebb8eb826b941a62c31d87ec9e904e7cbd8d0db167734a2f6d2bcfd

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0
+
+- Extracted from `rahendablog.github.io`'s `_plugins/md_alternates.rb`.
+- Generates a Markdown alternate at `/<slug>.md` for every written document in
+  the configured collections.
+- Configurable through `markdown_alternates:` in `_config.yml`: `enabled`,
+  `collections`, `index`, `extension`, `skip_key`, `authors_data`.
+- Adds the `markdown_alternate_url` Liquid filter.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahenda
+
+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,111 @@
+## About jekyll-geo-kit
+
+A Jekyll plugin that serves every post as clean Markdown alongside its HTML, so
+LLM crawlers and AI agents can read your content without parsing a page — GEO
+(Generative Engine Optimization).
+
+[![CI](https://github.com/rahendatri/jekyll-geo-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/rahendatri/jekyll-geo-kit/actions/workflows/ci.yml)
+
+
+## Quick start
+
+Add the gem to your site's `Gemfile`, in the `:jekyll_plugins` group so Bundler
+loads it for you:
+
+```ruby
+group :jekyll_plugins do
+  gem "jekyll-geo-kit"
+end
+```
+
+Then run `bundle install`.
+
+If you prefer to list your plugins in configuration instead, add it to
+`_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-geo-kit
+```
+
+That's it ! The plugin generates `.md` for every post.
+
+
+## Using GitHub Pages
+
+`jekyll-geo-kit` is a third-party plugin, so GitHub's own Jekyll builder will not 
+run it.
+
+Build your own workflow instead:
+
+1. Use or adapt the example here : [custom-jekyll-github-action](https://github.com/rahendatri/rahendatri.github.io/blob/main/.github/workflows/jekyll.yml)
+2.  Activate the custom Github Pages workflow by choosing `Github Actions` in the following place: `<project-settings> / Pages / Build and Deployment / Source`
+
+
+
+## What it does
+
+jekyll-geo-kit generates a Markdown alternate at `/<slug>.md` for every written
+document in the configured collections. Each one contains:
+
+* A pointer to your site index (`llms.txt` by default), so an agent that lands
+  on one document can discover the rest of the site
+* The document's metadata as plain lines — title, canonical source URL,
+  publication date, resolved author name, language
+* The description collapsed onto a single quoted line
+* The body exactly as you wrote it, still in Markdown and never converted to
+  HTML
+
+It also includes the `markdown_alternate_url` Liquid filter, so the
+`<link rel="alternate" type="text/markdown">` you put in `head.html` derives its
+path through the same logic the generator used and the two cannot drift apart.
+
+```
+> ## Site index
+> Fetch the complete site index at: https://example.com/llms.txt
+> Use it to discover every page on this site before exploring further.
+
+# A published post
+Source: https://example.com/2026/01/15/a-post.html
+Published: 2026-01-15
+Author: Rahenda
+Language: en
+
+> The post description, collapsed onto one line.
+
+The body of the post, exactly as written, still in Markdown.
+```
+
+While you could write this generator yourself, jekyll-geo-kit keeps the served
+paths, the metadata format and the `rel=alternate` declaration in one place.
+
+## What it doesn't do
+
+jekyll-geo-kit only generates the Markdown documents and the filter that links
+them. It does not write your `llms.txt` index — it links to whatever path you
+point `index` at, and leaves creating that file to you or to another plugin.
+
+It does not inject anything into your HTML. Declaring the alternates is a
+one-line Liquid snippet you add to your own `head.html`, documented under
+[Usage](docs/usage.md).
+
+It does not convert HTML to Markdown. The alternates carry the document's
+unrendered source body, so a document authored in Markdown round-trips exactly
+while one authored in HTML is served as that HTML.
+
+It covers collection documents — `posts` by default, any collection you
+configure — and not standalone pages like `about.md`.
+
+Being a third-party plugin, it does not run on GitHub's own Jekyll builder; see
+[Using GitHub Pages](#using-github-pages) for the workflow that does.
+
+## Documentation
+
+For more information, see:
+
+* [Usage](docs/usage.md)
+* [Advanced usage](docs/advanced-usage.md)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/jekyll-geo-kit/markdown_alternates/body.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module GeoKit
+    module MarkdownAlternates
+      # The Markdown text served at /<slug>.md: a pointer to the site index, the
+      # document's metadata as plain lines, then its unrendered body.
+      class Body
+        def initialize(site, document, config)
+          @site = site
+          @document = document
+          @config = config
+        end
+
+        def to_s
+          (banner + heading + description + content).join("\n")
+        end
+
+        private
+
+        def banner
+          index_url = @config.index_url
+          return [] if index_url.nil?
+
+          [
+            "> ## Site index",
+            "> Fetch the complete site index at: #{index_url}",
+            "> Use it to discover every page on this site before exploring further.",
+            "",
+          ]
+        end
+
+        def heading
+          lines = ["# #{@document.data["title"]}"]
+          lines << "Source: #{MarkdownAlternates.absolute_url(@site, @document.url)}"
+          lines << "Published: #{date.strftime("%Y-%m-%d")}" if date
+          lines << "Author: #{author_name}" if author_name
+          lines << "Language: #{language}"
+          lines
+        end
+
+        def description
+          text = @document.data["description"].to_s.strip.gsub(/\s+/, " ")
+          return [] if text.empty?
+
+          ["", "> #{text}"]
+        end
+
+        def content
+          ["", @document.content.to_s.strip, ""]
+        end
+
+        def date
+          @document.data["date"] || (@document.respond_to?(:date) ? @document.date : nil)
+        end
+
+        # Prefers the matching entry in _data/<authors_data>.yml, then the site's
+        # single-author config.
+        def author_name
+          key = @document.data["author"].to_s
+          author = @site.data.dig(@config.authors_data, key) || {}
+          name = author["name"] if author.is_a?(Hash)
+          name ||= @site.config.dig("author", "name")
+          name ||= (key unless key.empty?)
+          name
+        end
+
+        def language
+          @document.data["lang"] || @site.config["lang"] || "en"
+        end
+      end
+    end
+  end
+end

data/lib/jekyll-geo-kit/markdown_alternates/config.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module GeoKit
+    module MarkdownAlternates
+      # The `markdown_alternates:` block of _config.yml, with the defaults a site
+      # gets when it says nothing at all.
+      class Config
+        DEFAULTS = {
+          "enabled"      => true,
+          "collections"  => ["posts"],
+          "index"        => "/llms.txt",
+          "extension"    => ".md",
+          "skip_key"     => "unlisted",
+          "authors_data" => "authors",
+        }.freeze
+
+        def initialize(site)
+          @site = site
+          overrides = site.config["markdown_alternates"]
+          @options = DEFAULTS.merge(overrides.is_a?(Hash) ? overrides : {})
+        end
+
+        def enabled?
+          @options["enabled"] != false
+        end
+
+        def collections
+          Array(@options["collections"]).map(&:to_s)
+        end
+
+        def extension
+          ext = @options["extension"].to_s
+          ext.empty? ? DEFAULTS["extension"] : ext
+        end
+
+        # Front-matter key that excludes a document from the alternates, e.g.
+        # `unlisted: true`. Set to nil/false to generate one for every document.
+        def skip_key
+          key = @options["skip_key"]
+          return nil if key.nil? || key == false || key.to_s.empty?
+
+          key.to_s
+        end
+
+        def authors_data
+          @options["authors_data"].to_s
+        end
+
+        # Absolute URL of the site index linked at the top of every alternate, or
+        # nil when the site has none and the banner should be left out.
+        def index_url
+          path = @options["index"]
+          return nil if path.nil? || path == false || path.to_s.empty?
+
+          MarkdownAlternates.absolute_url(@site, path)
+        end
+      end
+    end
+  end
+end

data/lib/jekyll-geo-kit/markdown_alternates/filters.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module GeoKit
+    module MarkdownAlternates
+      # Liquid filter so a template links the alternate through the same path
+      # logic the generator used:
+      #
+      #   <link rel="alternate" type="text/markdown"
+      #         href="{{ page.url | markdown_alternate_url }}">
+      module Filters
+        def markdown_alternate_url(url)
+          site = @context.registers[:site]
+          extension = Config.new(site).extension
+          path = MarkdownAlternates.alternate_path(url, extension)
+
+          baseurl = site.config["baseurl"].to_s.chomp("/")
+          "#{baseurl}#{path}"
+        end
+      end
+    end
+  end
+end
+
+Liquid::Template.register_filter(Jekyll::GeoKit::MarkdownAlternates::Filters)

data/lib/jekyll-geo-kit/markdown_alternates/generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module GeoKit
+    module MarkdownAlternates
+      class Generator < Jekyll::Generator
+        safe true
+        priority :low
+
+        def generate(site)
+          config = Config.new(site)
+          return unless config.enabled?
+
+          documents(site, config).each do |document|
+            next if skip?(document, config)
+
+            site.pages << Page.new(site, document, config)
+          end
+        end
+
+        private
+
+        def documents(site, config)
+          config.collections.flat_map do |label|
+            collection = site.collections[label]
+            collection ? collection.docs : []
+          end
+        end
+
+        # Leaves out drafts, `published: false`, output-less collections and
+        # anything the site marks with the configured skip key.
+        def skip?(document, config)
+          return true unless document.write?
+
+          key = config.skip_key
+          return false if key.nil?
+
+          document.data[key] == true
+        end
+      end
+    end
+  end
+end

data/lib/jekyll-geo-kit/markdown_alternates/page.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module GeoKit
+    module MarkdownAlternates
+      # The generated page for one document's Markdown alternate.
+      #
+      # The source name ends in .txt on purpose: Jekyll picks its converter from
+      # the source extension, so a .txt name leaves the Markdown body alone, while
+      # the permalink decides the served path (/<slug>.md) and the output
+      # extension. GitHub Pages serves .md as text/markdown; charset=utf-8.
+      class Page < Jekyll::PageWithoutAFile
+        def initialize(site, document, config)
+          super(site, site.source, "", "#{document.basename_without_ext}.txt")
+
+          self.data = {
+            "layout"    => nil,
+            "permalink" => MarkdownAlternates.alternate_path(document.url, config.extension),
+            "sitemap"   => false,
+            "title"     => document.data["title"],
+          }
+          self.content = Body.new(site, document, config).to_s
+        end
+      end
+    end
+  end
+end

data/lib/jekyll-geo-kit/markdown_alternates.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "markdown_alternates/config"
+require_relative "markdown_alternates/body"
+require_relative "markdown_alternates/page"
+require_relative "markdown_alternates/generator"
+require_relative "markdown_alternates/filters"
+
+# Markdown alternates: /<slug>.md for every published document.
+#
+# An AI agent that lands on a page can fetch the same text as Markdown instead
+# of parsing the HTML, and finds a pointer to the site index at the top of it.
+# Declare the pages from head.html with
+# <link rel="alternate" type="text/markdown">.
+module Jekyll
+  module GeoKit
+    module MarkdownAlternates
+      # Joins site.url and site.baseurl onto an absolute path. Jekyll's own
+      # absolute_url filter needs a Liquid context, so the generator does it here.
+      def self.absolute_url(site, path)
+        base = site.config["url"].to_s.chomp("/")
+        baseurl = site.config["baseurl"].to_s
+        baseurl = "" if baseurl == "/"
+        "#{base}#{baseurl.chomp("/")}#{path}"
+      end
+
+      # The served path of a document's Markdown alternate: /a/post/ -> /a/post.md
+      def self.alternate_path(url, extension = ".md")
+        url.to_s.sub(%r{\.html\z}, "").sub(%r{/\z}, "") + extension
+      end
+    end
+  end
+end

data/lib/jekyll-geo-kit/version.rb

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

data/lib/jekyll-geo-kit.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "jekyll"
+
+require_relative "jekyll-geo-kit/version"
+require_relative "jekyll-geo-kit/markdown_alternates"
+
+# GEO (Generative Engine Optimization) features for a Jekyll site, one module
+# per feature.
+module Jekyll
+  module GeoKit
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-geo-kit
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Rahenda
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-24 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: 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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Generates /<slug>.md companions for each post, declared via rel=alternate
+  type=text/markdown, so LLM crawlers and AI agents can fetch clean Markdown instead
+  of parsing HTML. Each document links back to the site's llms.txt index.
+email:
+- rahendatri@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/jekyll-geo-kit.rb
+- lib/jekyll-geo-kit/markdown_alternates.rb
+- lib/jekyll-geo-kit/markdown_alternates/body.rb
+- lib/jekyll-geo-kit/markdown_alternates/config.rb
+- lib/jekyll-geo-kit/markdown_alternates/filters.rb
+- lib/jekyll-geo-kit/markdown_alternates/generator.rb
+- lib/jekyll-geo-kit/markdown_alternates/page.rb
+- lib/jekyll-geo-kit/version.rb
+homepage: https://github.com/rahendatri/jekyll-geo-kit
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/rahendatri/jekyll-geo-kit
+  bug_tracker_uri: https://github.com/rahendatri/jekyll-geo-kit/issues
+  changelog_uri: https://github.com/rahendatri/jekyll-geo-kit/blob/main/CHANGELOG.md
+  keywords: jekyll, geo, generative-engine-optimization, llms-txt, markdown, ai-crawlers,
+    seo
+post_install_message:
+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: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'GEO (Generative Engine Optimization) for Jekyll: serve every post as a Markdown
+  alternate'
+test_files: []