trifle-docs 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f51e6c6b892eaca5b790d652ccb970146c9e98b624cf3353c84af3ffb95ed4c
-  data.tar.gz: f5058c9fa39c81a635db554fabffaab5535f57a76a078138319df0e72732cd49
+  metadata.gz: 4660d54f61927575620d127f9493bc2921bf4a0395362acd2f71b4eeaee38712
+  data.tar.gz: c59600b536c976dbf67eaf4f99a61d214b1022b6a18795cc7ea37d9f5caf4ba7
 SHA512:
-  metadata.gz: 48ce9ec16b882be46f90825f0e12bb13c783fa16e5b22f5eae27551418a5e58d112a321496fdf46810474c68de5f8933661931a696b6378bc836ffd7a8e74192
-  data.tar.gz: 9721a213e1f2cef167e0adf4ed18025b0740ba6594e26f6f0f326e4e6412631f5957447f503cd2ca45c4ce4e2df5efb497a15a8aaf2943a29b246a2c373869a8
+  metadata.gz: fc4c3fa9f2d46e94c6a7a19169830b33c2601fbc2a39360945d57691332b3d3a6d00be8fdc12aa13a379595aefd655f887c02dcbd3ceda561c6431fdda1b0d2d
+  data.tar.gz: cd867ffc069b37ee0e513893abe097c8ed4c6a5ecdd8e7fb1d47c0fd0c33f950892024ca04ac653f3281383aab64cb3d7c88671ee5b5b8579b543b49112b3745

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    trifle-docs (0.7.0)
+    trifle-docs (0.7.2)
       redcarpet
       rouge
       sinatra

data/README.md

@@ -41,6 +41,8 @@ require 'trifle/docs'
 Trifle::Docs.configure do |config|
   config.path = File.join(__dir__, 'docs')
   config.views = File.join(__dir__, 'templates')
+  # Optional: canonical base URL used for absolute <loc> values in sitemap.xml
+  # config.sitemap_base_url = ENV.fetch('TRIFLE_DOCS_SITEMAP_BASE_URL', nil)
   config.register_harvester(Trifle::Docs::Harvester::Markdown)
   config.register_harvester(Trifle::Docs::Harvester::File)
 end
@@ -110,6 +112,22 @@ There are several variables available in your template file (except `layout.erb`
 - **Caching support** - Optional caching for production environments
 - **Navigation helpers** - Automatic menu and breadcrumb generation
 
+## Sitemap URL configuration
+
+`/sitemap.xml` emits absolute URLs. By default, Trifle::Docs uses the incoming request host (`request.base_url`).
+
+If your app runs behind a proxy/ingress and you need a canonical public domain, set:
+
+```ruby
+config.sitemap_base_url = 'https://docs.trifle.io'
+```
+
+In containerized deployments you can wire this through an env var, for example:
+
+```ruby
+config.sitemap_base_url = ENV.fetch('TRIFLE_DOCS_SITEMAP_BASE_URL', nil)
+```
+
 ## Harvesters
 
 Trifle::Docs supports multiple content processors:

data/lib/trifle/docs/app.rb

@@ -4,65 +4,11 @@ require 'sinatra/base'
 
 module Trifle
   module Docs
-    class App < Sinatra::Base
-      configure do
-        set :bind, '0.0.0.0'
-        set :views, proc { Trifle::Docs.default.views }
-      end
-
-      get '/search' do
-        results = Trifle::Docs.search(query: params['query'], scope: params['scope'])
-        erb(
-          'search'.to_sym,
-          {},
-          {
-            results: results,
-            query: params['query'],
-            scope: params['scope'],
-            sitemap: Trifle::Docs.sitemap,
-            meta: { description: 'Search' }
-          }
-        )
-      end
-
-      get '/llms.txt' do
-        meta = Trifle::Docs.meta(url: 'llms.txt')
-        return send_file(meta['path']) if meta && meta['type'] == 'file'
-
-        content = Trifle::Docs::Helper::Llms.homepage_markdown
-        halt(404, 'Not Found') if content.nil?
-
-        content_type 'text/markdown'
-        content
-      end
-
-      get '/llms-full.txt' do
-        meta = Trifle::Docs.meta(url: 'llms-full.txt')
-        return send_file(meta['path']) if meta && meta['type'] == 'file'
-
-        content = Trifle::Docs::Helper::Llms.full_markdown
-        halt(404, 'Not Found') if content.nil? || content.strip.empty?
-
-        content_type 'text/markdown'
-        content
-      end
-
-      get '/sitemap.xml' do
-        meta = Trifle::Docs.meta(url: 'sitemap.xml')
-        return send_file(meta['path']) if meta && meta['type'] == 'file'
-
-        render_generated_sitemap
-      end
-
-      get '/*' do
-        handle_request(params, request)
-      end
-
+    module AppHelpers
       def markdown_requested?(request, params)
         return true if params['format'].to_s.downcase == 'md'
 
-        accept = request.env['HTTP_ACCEPT'].to_s
-        accept.include?('text/markdown')
+        request.env['HTTP_ACCEPT'].to_s.include?('text/markdown')
       end
 
       def render_markdown?(meta, request, params)
@@ -77,18 +23,18 @@ module Trifle
         meta = Trifle::Docs.meta(url: url)
         halt(404, 'Not Found') if meta.nil?
 
+        set_vary_header unless file_meta?(meta)
         return render_markdown(meta, url) if render_markdown?(meta, request, params)
-        return send_file(meta['path']) if meta['type'] == 'file'
+        return send_file(meta['path']) if file_meta?(meta)
 
         render_html(meta, url)
       end
 
       def render_markdown(meta, url)
-        content_type 'text/markdown'
+        content_type markdown_content_type(request)
         Trifle::Docs::Helper::MarkdownLayout.render(
           meta: meta,
-          raw_content: Trifle::Docs.raw_content(url: url),
-          sitemap: Trifle::Docs.sitemap
+          raw_content: Trifle::Docs.raw_content(url: url)
         )
       end
 
@@ -103,14 +49,126 @@ module Trifle
       end
 
       def render_generated_sitemap
-        content = Trifle::Docs::Helper::Sitemap.xml
+        base_url = Trifle::Docs.default.sitemap_base_url || request.base_url
+        content = Trifle::Docs::Helper::Sitemap.xml(base_url: base_url)
         halt(404, 'Not Found') if content.nil? || content.strip.empty?
 
         content_type 'application/xml'
         content
       end
 
-      private :handle_request
+      def markdown_content_type(request)
+        return 'text/plain' if Trifle::Docs::Helper::AiDetection.ai_scraper?(request.user_agent)
+
+        'text/markdown'
+      end
+
+      def set_vary_header
+        headers['Vary'] = append_vary(headers['Vary'], 'User-Agent')
+        headers['Vary'] = append_vary(headers['Vary'], 'Accept')
+      end
+
+      def render_llms_for(base_url, full:)
+        base_url = normalize_base_url(base_url)
+        url = llms_url(base_url, full: full)
+        meta = Trifle::Docs.meta(url: url)
+        return send_file(meta['path']) if file_meta?(meta)
+
+        content = llms_content(full: full, base_url: base_url)
+        halt(404, 'Not Found') if llms_missing?(content, full: full)
+
+        content_type 'text/plain'
+        content
+      end
+
+      private
+
+      def append_vary(existing, value)
+        values = existing.to_s.split(',').map(&:strip).reject(&:empty?)
+        return value if values.empty?
+        return existing if values.any? { |entry| entry.casecmp(value).zero? }
+
+        (values + [value]).join(', ')
+      end
+
+      def normalize_base_url(base_url)
+        base_url.to_s.gsub(%r{^/+}, '').gsub(%r{/+$}, '')
+      end
+
+      def llms_url(base_url, full:)
+        llms_name = full ? 'llms-full.txt' : 'llms.txt'
+        [base_url, llms_name].reject(&:empty?).join('/')
+      end
+
+      def llms_content(full:, base_url:)
+        if full
+          Trifle::Docs::Helper::Llms.full_markdown(base_url: base_url)
+        else
+          Trifle::Docs::Helper::Llms.homepage_markdown(base_url: base_url)
+        end
+      end
+
+      def llms_missing?(content, full:)
+        return true if content.nil?
+        return false unless full
+
+        content.strip.empty?
+      end
+
+      def file_meta?(meta)
+        meta && meta['type'] == 'file'
+      end
+    end
+
+    class App < Sinatra::Base
+      configure do
+        set :bind, '0.0.0.0'
+        set :views, proc { Trifle::Docs.default.views }
+      end
+
+      helpers AppHelpers
+
+      get '/search' do
+        results = Trifle::Docs.search(query: params['query'], scope: params['scope'])
+        erb(
+          'search'.to_sym,
+          {},
+          {
+            results: results,
+            query: params['query'],
+            scope: params['scope'],
+            sitemap: Trifle::Docs.sitemap,
+            meta: { description: 'Search' }
+          }
+        )
+      end
+
+      get '/llms.txt' do
+        render_llms_for('', full: false)
+      end
+
+      get %r{/(.+)/llms\.txt} do |path|
+        render_llms_for(path, full: false)
+      end
+
+      get '/llms-full.txt' do
+        render_llms_for('', full: true)
+      end
+
+      get %r{/(.+)/llms-full\.txt} do |path|
+        render_llms_for(path, full: true)
+      end
+
+      get '/sitemap.xml' do
+        meta = Trifle::Docs.meta(url: 'sitemap.xml')
+        return send_file(meta['path']) if meta && meta['type'] == 'file'
+
+        render_generated_sitemap
+      end
+
+      get '/*' do
+        handle_request(params, request)
+      end
     end
   end
 end

data/lib/trifle/docs/configuration.rb

@@ -3,13 +3,14 @@
 module Trifle
   module Docs
     class Configuration
-      attr_accessor :path, :views, :layout, :namespace, :cache
+      attr_accessor :path, :views, :layout, :namespace, :cache, :sitemap_base_url
 
       def initialize
         @harvesters = []
         @path = nil
         @namespace = nil
         @cache = true
+        @sitemap_base_url = nil
       end
 
       def harvester

data/lib/trifle/docs/engine.rb

@@ -19,6 +19,8 @@ if Object.const_defined?('Rails')
             root to: 'page#show'
             get 'llms.txt', to: 'page#llms'
             get 'llms-full.txt', to: 'page#llms_full'
+            get '*path/llms.txt', to: 'page#llms'
+            get '*path/llms-full.txt', to: 'page#llms_full'
             get 'sitemap.xml', to: 'page#sitemap'
             get 'search', to: 'page#search'
             get '*url', to: 'page#show'
@@ -37,7 +39,7 @@ if Object.const_defined?('Rails')
           return render_not_found if content.nil?
           return render_not_found if !allow_empty && content.strip.empty?
 
-          render plain: content, content_type: 'text/markdown'
+          render plain: content, content_type: 'text/plain'
         end
 
         def render_sitemap(url)
@@ -71,9 +73,8 @@ if Object.const_defined?('Rails')
         def render_markdown(url:, meta:)
           render plain: Trifle::Docs::Helper::MarkdownLayout.render(
             meta: meta,
-            raw_content: Trifle::Docs.raw_content(url: url, config: configuration),
-            sitemap: Trifle::Docs.sitemap(config: configuration)
-          ), content_type: 'text/markdown'
+            raw_content: Trifle::Docs.raw_content(url: url, config: configuration)
+          ), content_type: markdown_content_type
         end
 
         def fetch_meta(url)
@@ -81,6 +82,7 @@ if Object.const_defined?('Rails')
         end
 
         def render_for_meta(meta, url, wants_md, request)
+          set_vary_header unless file_meta?(meta)
           return render_markdown(url: url, meta: meta) if render_markdown?(meta, wants_md, request)
           return render_file(meta: meta) if file_meta?(meta)
 
@@ -99,6 +101,10 @@ if Object.const_defined?('Rails')
           [url, wants_md]
         end
 
+        def llms_scope
+          params[:path].to_s.gsub(%r{^/+}, '').gsub(%r{/+$}, '')
+        end
+
         def render_markdown?(meta, wants_md, request)
           return false if meta['type'] == 'file'
 
@@ -110,6 +116,25 @@ if Object.const_defined?('Rails')
 
           request.headers['Accept'].to_s.include?('text/markdown')
         end
+
+        def markdown_content_type
+          return 'text/plain' if Trifle::Docs::Helper::AiDetection.ai_scraper?(request.user_agent)
+
+          'text/markdown'
+        end
+
+        def set_vary_header
+          response.headers['Vary'] = append_vary(response.headers['Vary'], 'User-Agent')
+          response.headers['Vary'] = append_vary(response.headers['Vary'], 'Accept')
+        end
+
+        def append_vary(existing, value)
+          values = existing.to_s.split(',').map(&:strip).reject(&:empty?)
+          return value if values.empty?
+          return existing if values.any? { |entry| entry.casecmp(value).zero? }
+
+          (values + [value]).join(', ')
+        end
       end
 
       class PageController < ActionController::Base
@@ -146,20 +171,31 @@ if Object.const_defined?('Rails')
         end
 
         def llms
-          render_llms('llms.txt', allow_empty: true) do
-            Trifle::Docs::Helper::Llms.homepage_markdown(config: configuration)
+          base_url = llms_scope
+          llms_url = [base_url, 'llms.txt'].reject(&:empty?).join('/')
+          render_llms(llms_url, allow_empty: true) do
+            Trifle::Docs::Helper::Llms.homepage_markdown(
+              config: configuration,
+              base_url: base_url
+            )
           end
         end
 
         def llms_full
-          render_llms('llms-full.txt') do
-            Trifle::Docs::Helper::Llms.full_markdown(config: configuration)
+          base_url = llms_scope
+          llms_url = [base_url, 'llms-full.txt'].reject(&:empty?).join('/')
+          render_llms(llms_url) do
+            Trifle::Docs::Helper::Llms.full_markdown(
+              config: configuration,
+              base_url: base_url
+            )
           end
         end
 
         def sitemap
+          base_url = configuration.sitemap_base_url || request.base_url
           render_sitemap('sitemap.xml') do
-            Trifle::Docs::Helper::Sitemap.xml(config: configuration)
+            Trifle::Docs::Helper::Sitemap.xml(config: configuration, base_url: base_url)
           end
         end
       end

data/lib/trifle/docs/helper/llms.rb

@@ -6,32 +6,56 @@ module Trifle
       module Llms
         module_function
 
-        def homepage_markdown(config: nil)
-          meta = Trifle::Docs.meta(url: '', config: config)
+        def homepage_markdown(config: nil, base_url: '')
+          base_url = normalize_base_url(base_url)
+          meta = Trifle::Docs.meta(url: base_url, config: config)
           return nil if meta.nil?
 
           Trifle::Docs::Helper::MarkdownLayout.render(
             meta: meta,
-            raw_content: Trifle::Docs.raw_content(url: '', config: config),
-            sitemap: Trifle::Docs.sitemap(config: config)
+            raw_content: Trifle::Docs.raw_content(url: base_url, config: config)
           )
         end
 
-        def full_markdown(config: nil)
+        def full_markdown(config: nil, base_url: '')
+          pages = llms_pages(config: config, base_url: base_url)
+          return nil if pages.nil?
+
+          pages.filter_map { |page| render_llms_page(page, config: config) }
+               .join("\n\n")
+        end
+
+        def llms_pages(config:, base_url:)
+          base_url = normalize_base_url(base_url)
           sitemap = Trifle::Docs.sitemap(config: config)
-          pages = flatten_sitemap(sitemap)
+          scoped_sitemap = sitemap_subtree(sitemap, base_url)
+          return nil if scoped_sitemap.nil?
 
-          chunks = pages.filter_map do |page|
-            meta = page[:meta]
-            next if meta.nil? || meta['type'] == 'file'
+          path = base_url.empty? ? [] : base_url.split('/')
+          flatten_sitemap(scoped_sitemap, path)
+        end
 
-            raw = Trifle::Docs.raw_content(url: page[:url], config: config)
-            next if raw.nil? || raw.strip.empty?
+        def render_llms_page(page, config:)
+          meta = page[:meta]
+          return nil if meta.nil? || meta['type'] == 'file'
 
-            format_page(meta: meta, url: page[:url], raw_content: raw)
-          end
+          raw = Trifle::Docs.raw_content(url: page[:url], config: config)
+          return nil if raw.nil? || raw.strip.empty?
+
+          format_page(meta: meta, url: page[:url], raw_content: raw)
+        end
+
+        def sitemap_subtree(sitemap, base_url)
+          return nil unless sitemap.is_a?(Hash)
+
+          base_url = normalize_base_url(base_url)
+          return sitemap if base_url.empty?
+
+          sitemap.dig(*base_url.split('/'))
+        end
 
-          chunks.join("\n\n")
+        def normalize_base_url(base_url)
+          base_url.to_s.gsub(%r{^/+}, '').gsub(%r{/+$}, '')
         end
 
         def flatten_sitemap(node, path = [])

data/lib/trifle/docs/helper/markdown_layout.rb

@@ -6,15 +6,12 @@ module Trifle
       module MarkdownLayout
         module_function
 
-        def render(meta:, raw_content:, sitemap:) # rubocop:disable Metrics/MethodLength
+        def render(meta:, raw_content:)
           lines = []
           title = meta['title'] || derive_title_from_url(meta['url'])
 
           lines << "# #{title}"
           lines << ''
-          lines << '## Navigation'
-          lines << navigation_toc(sitemap)
-          lines << ''
           lines << '## Content'
           lines << raw_content.to_s.strip
           lines << ''

data/lib/trifle/docs/helper/sitemap.rb

@@ -2,6 +2,7 @@
 
 require 'cgi'
 require 'time'
+require 'uri'
 
 module Trifle
   module Docs
@@ -9,9 +10,10 @@ module Trifle
       module Sitemap
         module_function
 
-        def xml(config: nil)
+        def xml(config: nil, base_url: nil)
           sitemap = Trifle::Docs.sitemap(config: config)
-          urls = sitemap_urls(sitemap)
+          resolved_base_url = resolve_base_url(config: config, base_url: base_url)
+          urls = sitemap_urls(sitemap, base_url: resolved_base_url)
           return nil if urls.empty?
 
           build_document(urls)
@@ -31,13 +33,13 @@ module Trifle
           entries
         end
 
-        def sitemap_urls(sitemap)
+        def sitemap_urls(sitemap, base_url: nil)
           entries = flatten_sitemap(sitemap)
           entries.filter_map do |entry|
             meta = entry[:meta]
             next if meta.nil? || meta['type'] == 'file'
 
-            build_url_entry(entry[:url], meta)
+            build_url_entry(entry[:url], meta, base_url: base_url)
           end
         end
 
@@ -50,21 +52,59 @@ module Trifle
           ].join("\n")
         end
 
-        def build_url_entry(url, meta)
-          loc = normalize_loc(url, meta)
+        def build_url_entry(url, meta, base_url: nil)
+          loc = normalize_loc(url, meta, base_url: base_url)
           lastmod = format_lastmod(meta['updated_at'])
           lastmod_tag = lastmod ? "<lastmod>#{lastmod}</lastmod>" : ''
 
           "<url><loc>#{loc}</loc>#{lastmod_tag}</url>"
         end
 
-        def normalize_loc(url, meta)
+        def normalize_loc(url, meta, base_url: nil)
           loc = meta['url']
           loc = "/#{url}" if loc.nil? || loc.empty?
           loc = '/' if loc == '//'
+          loc = absolutize_loc(loc, base_url)
           CGI.escapeHTML(loc)
         end
 
+        def absolutize_loc(loc, base_url)
+          return loc if base_url.nil? || absolute_url?(loc)
+
+          path = loc.to_s.gsub(%r{^/+}, '')
+          return "#{base_url}/" if path.empty?
+
+          "#{base_url}/#{path}"
+        end
+
+        def absolute_url?(loc)
+          loc.to_s.match?(%r{\Ahttps?://}i)
+        end
+
+        def resolve_base_url(config:, base_url:)
+          normalize_base_url(base_url) || normalize_base_url(configuration_base_url(config))
+        end
+
+        def configuration_base_url(config)
+          return nil unless config.respond_to?(:sitemap_base_url)
+
+          config.sitemap_base_url
+        end
+
+        def normalize_base_url(base_url)
+          value = base_url.to_s.strip
+          return nil if value.empty?
+
+          uri = URI.parse(value)
+          return nil unless uri.is_a?(URI::HTTP) && uri.host
+
+          uri.query = nil
+          uri.fragment = nil
+          uri.to_s.gsub(%r{/+$}, '')
+        rescue URI::InvalidURIError
+          nil
+        end
+
         def format_lastmod(value)
           return nil if value.nil?
 

data/lib/trifle/docs/version.rb

@@ -2,6 +2,6 @@
 
 module Trifle
   module Docs
-    VERSION = '0.7.0'
+    VERSION = '0.7.2'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trifle-docs
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.2
 platform: ruby
 authors:
 - Jozef Vaclavik
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-27 00:00:00.000000000 Z
+date: 2026-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler