ligarb 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fff2a914d9209b69c1b9c35d4133accfe0d5dcc4e272779959baa9c3bba64cf0
-  data.tar.gz: da08e338979034ba836c2321adb4820f91231e942a6bedb0e7ffb31128271c52
+  metadata.gz: 4ba0a513e610d71f30b92bf61b42e2acdab5516e6105b56a43603692c60a3a9a
+  data.tar.gz: 5824b715da62d8d568d597a2edc0dc9a85dc0b7b7ef028499d7ce9cbcb65d161
 SHA512:
-  metadata.gz: 6880ee104849e3904dad11583a8b635dc3bf105acea215df197ab4acbe1dcffa432b5c45c0c471d84424f22c7f287c2b11dc553f987c99d2613948d1f01eb766
-  data.tar.gz: c230438379c7ff16c808b38835fe0ea764b88433e109ce0573caba710163ec3efddb86975251faa145525176946a543b70eb44670fc55718998fade9098bf7c7
+  metadata.gz: c58b836062f00ef965e59f44fef837fe0551d22a57f93f957b0a25d718b18ef79447b11b50f8c4a52540fec9d96656397266d4500ecacc60e42faa474099abd3
+  data.tar.gz: f74f174bc842665f9d68387381cd92cfc9ee48745f1bf339d3f6393e96b17a7ddec0adbd561f8e56cfc92fd6a6b9eac6d3b102e4abc1e9f071407baa7870bbd2

data/assets/mermaid_check.mjs

@@ -47,7 +47,11 @@ function makeStub(name, overrides = {}) {
 globalThis.window = globalThis;
 // nodeType 9 = DOCUMENT_NODE; DOMPurify checks it to decide it has a real DOM.
 globalThis.document = makeStub("document", { nodeType: 9 });
-globalThis.navigator = { userAgent: "node" };
+// Node >= 21 ships a built-in read-only `navigator` global; assigning to it
+// throws a TypeError. Only define our stub when the runtime lacks one.
+if (!("navigator" in globalThis)) {
+  globalThis.navigator = { userAgent: "node" };
+}
 globalThis.addEventListener = noop;
 globalThis.location = { href: "http://localhost/", protocol: "http:" };
 globalThis.Element = function Element() {};

data/assets/style.css

@@ -77,6 +77,22 @@ body {
   opacity: 1;
 }
 
+.ai-md-hint {
+  margin: 0 0 1.5rem;
+  font-size: 0.8rem;
+  color: var(--color-text-muted);
+  opacity: 0.8;
+}
+
+.ai-md-hint a {
+  color: inherit;
+  text-decoration: underline;
+}
+
+@media print {
+  .ai-md-hint { display: none; }
+}
+
 .book-title {
   font-size: 1.1rem;
   font-weight: 700;

data/docs/help.md

@@ -83,6 +83,23 @@ The output directory contains index.html plus js/ and css/ subdirectories
 for auto-downloaded libraries (highlight.js, mermaid, KaTeX, etc.).
 Open index.html directly in a browser — no web server needed.
 
+The build also emits a Markdown full-text version of the book next to
+index.html, intended for AI/LLM readers (HTML is noisy and costly to read;
+clean Markdown is cheaper and more faithful). For a single-language build it
+is `index.md`; for a multi-language (hub) build it is `index.<lang>.md` per
+language. Each is the concatenated chapter sources in reading order. The HTML
+points to it two ways: a small visible note at the top of the content ("For
+AI/LLM readers: a clean Markdown full-text version of this book is at …") and
+a `<link rel="alternate" type="text/markdown">` in the head. Both use a
+relative href (the bare filename), so they resolve against whatever URL the
+page is actually served from — local preview, staging, or production — rather
+than hard-coding `site_url` (the absolute canonical URL still lives in
+`og:url` / `<link rel="canonical">`). A fetcher resolves it against the page's
+own URL, so a model that fetched the page finds the bundle next to it. No tool
+is guaranteed to honor these automatically —
+the visible note is what actually reaches a model that fetched the page,
+since the in-page text is included in what the fetcher hands to the model.
+
 When `github_review.enabled` is true and `repository` is set (see
 Configuration below), the build also injects a static "Report as issue"
 feedback UI: readers select text, pick a type and add a comment, and a

data/lib/ligarb/builder.rb

@@ -41,13 +41,18 @@ module Ligarb
 
       bibliography = resolve_citations!(all_chapters)
 
+      FileUtils.mkdir_p(@config.output_path)
+
+      md_name = "index.md"
+      write_markdown_bundle(all_chapters, File.join(@config.output_path, md_name))
+
       html = Template.new.render(config: @config, chapters: all_chapters,
                                  structure: structure, assets: assets,
                                  index_entries: index_entries,
                                  bibliography: bibliography,
-                                 github_review: github_review_data(@config))
+                                 github_review: github_review_data(@config),
+                                 ai_md: md_name)
 
-      FileUtils.mkdir_p(@config.output_path)
       output_file = File.join(@config.output_path, "index.html")
       File.write(output_file, html)
 
@@ -76,6 +81,14 @@ module Ligarb
         all_lang_chapters.concat(lang_data[:chapters])
       end
 
+      FileUtils.mkdir_p(output_path)
+
+      langs.each do |ld|
+        md_name = "index.#{ld[:lang]}.md"
+        write_markdown_bundle(ld[:chapters], File.join(output_path, md_name))
+        ld[:ai_md] = md_name
+      end
+
       assets = AssetManager.new(output_path)
       assets.detect(all_lang_chapters)
       assets.provision!
@@ -428,6 +441,14 @@ module Ligarb
       text.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
     end
 
+    # Emit a clean Markdown full-text version of the book alongside index.html.
+    # AI/LLM readers (and the in-page hint) point here for low-noise content.
+    # The bundle is the concatenated chapter sources in flat reading order.
+    def write_markdown_bundle(chapters, path)
+      body = chapters.map { |ch| ch.source.strip }.reject(&:empty?).join("\n\n")
+      File.write(path, body.empty? ? body : "#{body}\n")
+    end
+
     def copy_images
       images_dir = File.join(@config.base_dir, "images")
       return unless Dir.exist?(images_dir)

data/lib/ligarb/chapter.rb

@@ -8,7 +8,7 @@ module Ligarb
     class CrossReferenceError < StandardError; end
 
     attr_reader :title, :slug, :html, :headings, :number, :appendix_letter, :index_entries, :cite_entries,
-                :path, :mermaid_blocks
+                :path, :mermaid_blocks, :source
     attr_accessor :part_title, :cover, :relative_path
 
     Heading = Struct.new(:level, :text, :id, :display_text, keyword_init: true)

data/lib/ligarb/config.rb

@@ -233,6 +233,9 @@ module Ligarb
 
     def load_translations_hub(data)
       @title = data.fetch("title", "")
+      # The hub writes its combined build here; serve needs output_path to work
+      # even though hub init returns before the normal output_dir assignment.
+      @output_dir = data.fetch("output_dir", "build")
       @translations = []
 
       trans = data["translations"]

data/lib/ligarb/template.rb

@@ -13,7 +13,7 @@ module Ligarb
       @css_path      = File.join(ASSETS_DIR, "style.css")
     end
 
-    def render(config:, chapters:, structure:, assets:, index_entries: [], bibliography: [], github_review: nil)
+    def render(config:, chapters:, structure:, assets:, index_entries: [], bibliography: [], github_review: nil, ai_md: nil)
       css = File.read(@css_path)
       template = File.read(@template_path)
 
@@ -42,6 +42,7 @@ module Ligarb
       b.local_variable_set(:og_description, og_description(config, chapters))
       b.local_variable_set(:og_locale, og_locale(config.language))
       b.local_variable_set(:og_url, og_url(config))
+      b.local_variable_set(:ai_md, ai_md)
 
       ERB.new(template, trim_mode: "-").result(b)
     end
@@ -74,6 +75,7 @@ module Ligarb
           footer: cfg.effective_footer,
           index_tree: build_index_tree(ld[:index_entries], ld[:chapters]),
           bibliography: ld[:bibliography],
+          ai_md: ld[:ai_md],
         }
       end
 
@@ -99,6 +101,7 @@ module Ligarb
       b.local_variable_set(:og_description, og_description(first_config, first[:chapters]))
       b.local_variable_set(:og_locale, og_locale(first_config.language))
       b.local_variable_set(:og_url, og_url(first_config))
+      b.local_variable_set(:ai_md, nil)
 
       ERB.new(template, trim_mode: "-").result(b)
     end

data/lib/ligarb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ligarb
-  VERSION = "0.9.1"
+  VERSION = "0.10.0"
 end

data/templates/book.html.erb

@@ -17,6 +17,15 @@
 <meta property="og:description" content="<%= h(og_description) %>">
 <%- end -%>
 <meta name="twitter:card" content="summary">
+<%- if multilang -%>
+<%- langs.each do |ld| -%>
+<%- if ld[:ai_md] -%>
+<link rel="alternate" type="text/markdown" hreflang="<%= h(ld[:language]) %>" href="<%= h(ld[:ai_md]) %>" title="<%= h(ld[:title]) %> (Markdown)">
+<%- end -%>
+<%- end -%>
+<%- elsif ai_md -%>
+<link rel="alternate" type="text/markdown" href="<%= h(ai_md) %>" title="Markdown version">
+<%- end -%>
 <%- if author && !author.to_s.empty? -%>
 <meta property="book:author" content="<%= h(author) %>">
 <%- end -%>
@@ -272,6 +281,15 @@
 <button class="sidebar-toggle" id="sidebar-toggle" aria-label="Toggle sidebar">&#9776;</button>
 
 <main class="content" id="content">
+<%- if multilang -%>
+  <%- langs.each do |ld| -%>
+  <%- if ld[:ai_md] -%>
+  <p class="ai-md-hint lang-content" data-lang="<%= ld[:lang] %>">For AI/LLM readers: a clean Markdown full-text version of this book is at <a href="<%= h(ld[:ai_md]) %>"><%= h(ld[:ai_md]) %></a>.</p>
+  <%- end -%>
+  <%- end -%>
+<%- elsif ai_md -%>
+  <p class="ai-md-hint">For AI/LLM readers: a clean Markdown full-text version of this book is at <a href="<%= h(ai_md) %>"><%= h(ai_md) %></a>.</p>
+<%- end -%>
 <%- if multilang -%>
   <%- langs.each do |ld| -%>
   <%- ld[:chapters].select(&:cover?).each do |chapter| -%>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ligarb
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - ligarb contributors