ligarb 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fff2a914d9209b69c1b9c35d4133accfe0d5dcc4e272779959baa9c3bba64cf0
-  data.tar.gz: da08e338979034ba836c2321adb4820f91231e942a6bedb0e7ffb31128271c52
+  metadata.gz: 4da7029fb2f9963b33dc85186479a6b76f279613837c8de76fba3b44f82431c8
+  data.tar.gz: '0648d1ad4d05539e4675a835c5970635cd08c560f75de5968cfc9f946371c40c'
 SHA512:
-  metadata.gz: 6880ee104849e3904dad11583a8b635dc3bf105acea215df197ab4acbe1dcffa432b5c45c0c471d84424f22c7f287c2b11dc553f987c99d2613948d1f01eb766
-  data.tar.gz: c230438379c7ff16c808b38835fe0ea764b88433e109ce0573caba710163ec3efddb86975251faa145525176946a543b70eb44670fc55718998fade9098bf7c7
+  metadata.gz: b500296a3a1f1d6b0065b40ccdbf3b043ebc8ee6ce8f3278979d2e82f736fc16a2774894f9bce84c757238c09d6f640f2c35524cf924b09b47f20c3bf9eae362
+  data.tar.gz: 599ec6de780340aa4c61c7dd7e539363890297102b7a800384089327dbb0dc9cbff2a4e0f1ee808be0b26b37357445d3762a2f8441a932254dd01b05aea816f6

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
@@ -182,6 +199,7 @@ The configuration file is a YAML file with the following fields:
 | `output_dir` | optional | `"build"` | Output directory relative to book.yml. |
 | `chapter_numbers` | optional | `true` | Show chapter/section numbers (e.g. "1.", "1.1", "1.1.1"). |
 | `style` | optional | — | Path to a custom CSS file relative to book.yml. Loaded after the default styles, so it can override any rule. |
+| `head` | optional | — | Raw HTML injected verbatim at the end of `<head>`. Use it for analytics beacons, search-console verification, custom meta tags, etc. Not sanitized (trusted-author model, like `style`). In a multi-language hub build it is shared across languages (set it once on the hub). See "Custom head HTML (analytics)". |
 | `repository` | optional | — | GitHub repository URL (e.g. "https://github.com/user/repo"). When set, each chapter shows a "View on GitHub" link pointing to `{repository}/blob/HEAD/{path-from-git-root}`. |
 | `ai_generated` | optional | `false` | Mark the book as AI-generated content. When true: adds an "AI Generated" badge in the sidebar header, adds a default disclaimer footer to each chapter, and adds noindex/noai meta tags. The footer text can be overridden with the `footer` field. |
 | `footer` | optional | — | Custom text displayed at the bottom of each chapter. Overrides the default ai_generated disclaimer if both are set. |
@@ -800,6 +818,35 @@ Example custom.css:
 }
 ```
 
+### Custom head HTML (analytics)
+
+GitHub Pages and most static hosts do not report page views (a repository's
+"Insights → Traffic" counts repo visits, not the rendered site). To measure
+traffic, add a small client-side beacon. The `head` field injects raw HTML
+verbatim at the end of `<head>`:
+
+```yaml
+head: |
+  <script data-goatcounter="https://MYCODE.goatcounter.com/count"
+          async src="//gc.zgo.at/count.js"></script>
+```
+
+The HTML is embedded as-is (no sanitization — trusted-author model, like
+`style`), so treat it as part of the trusted source. It is not limited to
+analytics: search-console verification tags, a custom `og:image`, or extra
+meta tags work too.
+
+[GoatCounter](https://www.goatcounter.com/) is a good fit for a personal site
+— free for non-commercial use, one script tag, no cookies (so no consent
+banner), and a per-page breakdown. [Cloudflare Web Analytics] and Google
+Analytics work the same way; just paste their snippet.
+
+[Cloudflare Web Analytics]: https://www.cloudflare.com/web-analytics/
+
+In a multi-language hub build, set `head` once on the hub config — it is
+inherited by every language, and the output is a single HTML page, so the
+snippet appears once.
+
 ### Dark Mode
 
 The generated HTML includes a dark mode toggle button (moon icon) in the

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

@@ -11,7 +11,7 @@ module Ligarb
     # config file that was directly passed to `ligarb build`.
     INHERITABLE_KEYS = %w[author language chapter_numbers style
                           repository ai_generated footer bibliography
-                          github_review site_url].freeze
+                          github_review site_url head].freeze
     # `description` is intentionally not inheritable: it is usually
     # language-specific, so each translation should set its own.
 
@@ -28,7 +28,7 @@ module Ligarb
     attr_reader :title, :author, :language, :output_dir, :base_dir,
                 :chapter_numbers, :structure, :style, :repository,
                 :ai_generated, :footer, :bibliography, :sources,
-                :translations, :github_review, :description, :site_url
+                :translations, :github_review, :description, :site_url, :head
 
     def initialize(path, parent_data: nil)
       @base_dir = File.dirname(File.expand_path(path))
@@ -74,6 +74,7 @@ module Ligarb
       @footer          = data.fetch("footer", nil)
       @bibliography    = data.fetch("bibliography", nil)
       @github_review   = data.fetch("github_review", nil)
+      @head            = data.fetch("head", nil)
       @sources         = parse_sources(data.fetch("sources", []))
       @structure       = parse_structure(data["chapters"])
       @translations    = []
@@ -233,6 +234,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,8 @@ 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)
+      b.local_variable_set(:head_html, config.head)
 
       ERB.new(template, trim_mode: "-").result(b)
     end
@@ -74,6 +76,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 +102,8 @@ 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)
+      b.local_variable_set(:head_html, first_config.head)
 
       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.11.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 -%>
@@ -43,6 +52,9 @@
 <%- if assets.need?(:katex) -%>
 <link rel="stylesheet" href="css/katex.min.css">
 <%- end -%>
+<%- if head_html && !head_html.to_s.empty? -%>
+<%= head_html %>
+<%- end -%>
 </head>
 <body>
 
@@ -272,6 +284,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.11.0
 platform: ruby
 authors:
 - ligarb contributors