ligarb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cc0976cad1fb731ff5ad56f38d7ee7142a0deecc158b70482f017df2611b678
-  data.tar.gz: 802ec24c33f96792addf6939cf92e04e7163e1b6864958dbfef7b8a02d224645
+  metadata.gz: 20b29dff31e22937e2ab71a7011d1ed2fb193c8717753c7a23500767645807f1
+  data.tar.gz: be6404f8dccb7cea765b8635f9663b57f0c23e73253a29da6ac49ca0017baae1
 SHA512:
-  metadata.gz: 58807bf5f3088e399d395761e75e65d52933db36ce116326e30a88b0ccb87425d4cde2644c89912e10b772f5565238b15384ada2fdd2ea261509eceded09ab97
-  data.tar.gz: 36069084a2b167996bf2310aa2bd17ee0689d59b52941fbb295b2c623eeb3f34e24a8ccd95bb12751ce23782c9df1374f3c8df8eaa46d24742f63beed146ec87
+  metadata.gz: 9ca9e973840571772b22b493ddfbc15b87c844abf05e84c2805c3d63ede347a3e245745e5bab2b8d2a3cb8d7b13b3c6c9d94f70b2d5c6d572eefadc11a839d64
+  data.tar.gz: 98f30f871f31b96331ebac03a4e0bb85690e612e14dd0412592ff2a1400a897698807d206f851143561e27bd384d32273517531708c2f1af7ee59aaaedf33c17

data/assets/style.css

@@ -376,6 +376,53 @@ mark.search-highlight {
   border-radius: 2px;
 }
 
+/* === Admonitions === */
+.admonition {
+  border-left: 4px solid;
+  border-radius: 0 4px 4px 0;
+  padding: 0.75rem 1rem;
+  margin-bottom: 1rem;
+}
+
+.admonition p:last-child {
+  margin-bottom: 0;
+}
+
+.admonition-title {
+  font-weight: 600;
+  margin-bottom: 0.4rem !important;
+}
+
+.admonition-note {
+  border-left-color: #2563eb;
+  background: #eff6ff;
+}
+.admonition-note .admonition-title::before { content: "\2139\FE0F  "; }
+
+.admonition-tip {
+  border-left-color: #16a34a;
+  background: #f0fdf4;
+}
+.admonition-tip .admonition-title::before { content: "\1F4A1  "; }
+
+.admonition-warning {
+  border-left-color: #ca8a04;
+  background: #fefce8;
+}
+.admonition-warning .admonition-title::before { content: "\26A0\FE0F  "; }
+
+.admonition-caution {
+  border-left-color: #dc2626;
+  background: #fef2f2;
+}
+.admonition-caution .admonition-title::before { content: "\1F6D1  "; }
+
+.admonition-important {
+  border-left-color: #9333ea;
+  background: #faf5ff;
+}
+.admonition-important .admonition-title::before { content: "\2757  "; }
+
 /* === Dark Mode === */
 [data-theme="dark"] {
   --color-bg: #1a1a2e;
@@ -390,6 +437,22 @@ mark.search-highlight {
   --color-code-border: #2d3748;
 }
 
+[data-theme="dark"] .admonition-note {
+  background: #1e2a3a;
+}
+[data-theme="dark"] .admonition-tip {
+  background: #1a2e1a;
+}
+[data-theme="dark"] .admonition-warning {
+  background: #2e2a1a;
+}
+[data-theme="dark"] .admonition-caution {
+  background: #2e1a1a;
+}
+[data-theme="dark"] .admonition-important {
+  background: #2a1a2e;
+}
+
 [data-theme="dark"] .search-box input {
   background: var(--color-code-bg);
   color: var(--color-text);
@@ -561,6 +624,52 @@ mark.search-highlight {
   }
 }
 
+/* === Index === */
+.index-group {
+  margin-bottom: 1.5rem;
+}
+
+.index-letter {
+  font-size: 1.3rem;
+  font-weight: 700;
+  color: var(--color-accent);
+  border-bottom: 2px solid var(--color-border);
+  padding-bottom: 0.25rem;
+  margin-bottom: 0.5rem;
+}
+
+.index-entries {
+  margin-left: 0;
+}
+
+.index-entries dt {
+  font-weight: 600;
+  margin-top: 0.4rem;
+}
+
+.index-entries dt.index-sub {
+  font-weight: 400;
+  margin-left: 1.5rem;
+}
+
+.index-entries dd {
+  margin-left: 1.5rem;
+  font-size: 0.92rem;
+}
+
+.index-entries dd.index-sub {
+  margin-left: 3rem;
+}
+
+.index-entries dd a {
+  color: var(--color-accent);
+  text-decoration: none;
+}
+
+.index-entries dd a:hover {
+  text-decoration: underline;
+}
+
 /* === Print === */
 @media print {
   .sidebar,
@@ -570,6 +679,14 @@ mark.search-highlight {
     display: none !important;
   }
 
+  html {
+    font-size: 11pt;
+  }
+
+  body {
+    line-height: 1.5;
+  }
+
   .content {
     margin-left: 0;
     max-width: 100%;
@@ -589,4 +706,17 @@ mark.search-highlight {
     white-space: pre-wrap;
     word-wrap: break-word;
   }
+
+  .chapter pre code {
+    font-size: 0.8rem;
+  }
+
+  @page {
+    margin: 20mm 15mm;
+    @bottom-center {
+      content: counter(page);
+      font-size: 9pt;
+      color: #666;
+    }
+  }
 }

data/lib/ligarb/builder.rb

@@ -16,14 +16,23 @@ module Ligarb
       structure = load_structure
 
       all_chapters = collect_all_chapters(structure)
+      resolve_cross_references(all_chapters)
       assign_relative_paths(all_chapters) if @config.repository
 
       assets = AssetManager.new(@config.output_path)
       assets.detect(all_chapters)
       assets.provision!
 
+      index_entries = all_chapters.flat_map { |ch|
+        ch.index_entries.map { |e|
+          e.class.new(term: e.term, display_text: e.display_text,
+                      chapter_slug: e.chapter_slug, anchor_id: e.anchor_id)
+        }
+      }
+
       html = Template.new.render(config: @config, chapters: all_chapters,
-                                 structure: structure, assets: assets)
+                                 structure: structure, assets: assets,
+                                 index_entries: index_entries)
 
       FileUtils.mkdir_p(@config.output_path)
       output_file = File.join(@config.output_path, "index.html")
@@ -98,6 +107,22 @@ module Ligarb
       end
     end
 
+    def resolve_cross_references(all_chapters)
+      chapter_map = {}
+      all_chapters.each do |ch|
+        abs_path = File.expand_path(ch.instance_variable_get(:@path))
+        chapter_map[abs_path] = {
+          slug: ch.slug,
+          chapter: ch,
+          headings: ch.headings.each_with_object({}) { |h, map| map[h.id] = h }
+        }
+      end
+
+      all_chapters.each do |ch|
+        ch.resolve_cross_references!(chapter_map)
+      end
+    end
+
     def assign_relative_paths(chapters)
       git_root = find_git_root(@config.base_dir)
       chapters.each do |ch|

data/lib/ligarb/chapter.rb

@@ -5,10 +5,13 @@ require "kramdown-parser-gfm"
 
 module Ligarb
   class Chapter
-    attr_reader :title, :slug, :html, :headings, :number, :appendix_letter
+    class CrossReferenceError < StandardError; end
+
+    attr_reader :title, :slug, :html, :headings, :number, :appendix_letter, :index_entries
     attr_accessor :part_title, :cover, :relative_path
 
     Heading = Struct.new(:level, :text, :id, :display_text, keyword_init: true)
+    IndexEntry = Struct.new(:term, :display_text, :chapter_slug, :anchor_id, keyword_init: true)
 
     def initialize(path, base_dir)
       @path     = path
@@ -42,6 +45,44 @@ module Ligarb
       @cover
     end
 
+    def self.generate_id(text)
+      text.downcase
+          .gsub(/[^\p{L}\p{N}\s_-]/u, "")
+          .strip
+          .gsub(/\s+/, "-")
+    end
+
+    def resolve_cross_references!(chapter_map)
+      source_dir = File.dirname(@path)
+
+      @html = @html.gsub(%r{<a\s+href="((?!https?://)[^"]+\.md)(?:#([^"]*))?">(.*?)</a>}m) do
+        href_path = $1
+        fragment = $2
+        link_text = $3
+
+        target_path = File.expand_path(href_path, source_dir)
+        entry = chapter_map[target_path]
+        unless entry
+          raise CrossReferenceError, "cross-reference target not found: #{href_path} (from #{File.basename(@path)})"
+        end
+
+        if fragment && !fragment.empty?
+          normalized = self.class.generate_id(fragment)
+          heading = entry[:headings][normalized]
+          unless heading
+            raise CrossReferenceError, "cross-reference heading not found: #{href_path}##{fragment} (from #{File.basename(@path)})"
+          end
+          anchor = "#{entry[:slug]}--#{heading.id}"
+          text = link_text.empty? ? heading.display_text : link_text
+        else
+          anchor = entry[:slug]
+          text = link_text.empty? ? entry[:chapter].display_title : link_text
+        end
+
+        %(<a href="##{anchor}">#{text}</a>)
+      end
+    end
+
     def display_title
       if @appendix_letter
         "#{@appendix_letter}. #{@title}"
@@ -60,7 +101,10 @@ module Ligarb
       @html = rewrite_image_paths(doc.to_html)
       @html = apply_heading_ids(@html)
       @html = convert_special_code_blocks(@html)
+      @html = convert_admonitions(@html)
       @html = scope_footnote_ids(@html)
+      @index_entries = []
+      @html = extract_index_markers(@html)
       @title = @headings.first&.text || @slug
     end
 
@@ -92,10 +136,7 @@ module Ligarb
     end
 
     def generate_id(text)
-      text.downcase
-          .gsub(/[^\p{L}\p{N}\s_-]/u, "") # keep letters (any script), digits, spaces, _, -
-          .strip
-          .gsub(/\s+/, "-")
+      self.class.generate_id(text)
     end
 
     def apply_heading_ids(html)
@@ -139,12 +180,65 @@ module Ligarb
       text.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
     end
 
+    ADMONITION_TITLES = {
+      "NOTE" => "Note",
+      "TIP" => "Tip",
+      "WARNING" => "Warning",
+      "CAUTION" => "Caution",
+      "IMPORTANT" => "Important",
+    }.freeze
+
+    def convert_admonitions(html)
+      html.gsub(%r{<blockquote>\s*<p>\[!(NOTE|TIP|WARNING|CAUTION|IMPORTANT)\]\s*\n?(.*?)</p>(.*?)</blockquote>}m) do
+        type = $1
+        first_content = $2.strip
+        rest = $3
+        css_class = type.downcase
+        title = ADMONITION_TITLES[type]
+
+        inner = if first_content.empty?
+                  rest
+                else
+                  "<p>#{first_content}</p>#{rest}"
+                end
+
+        %(<div class="admonition admonition-#{css_class}">\n<p class="admonition-title">#{title}</p>\n#{inner}</div>)
+      end
+    end
+
     def scope_footnote_ids(html)
       html.gsub(/(id="|href="#)(fn:|fnref:)(\w+)/) do
         "#{$1}#{$2}#{@slug}--#{$3}"
       end
     end
 
+    def extract_index_markers(html)
+      idx_count = 0
+      html.gsub(%r{<a\s+href="#index(?::([^"]*))?">(.*?)</a>}m) do
+        terms_str = $1
+        display_text = $2
+        anchor_id = "#{@slug}--idx-#{idx_count}"
+        idx_count += 1
+
+        terms = if terms_str && !terms_str.empty?
+                  terms_str.split(",").map(&:strip)
+                else
+                  [display_text.gsub(/<[^>]+>/, "")]  # strip any HTML tags for the term
+                end
+
+        terms.each do |term|
+          @index_entries << IndexEntry.new(
+            term: term,
+            display_text: display_text,
+            chapter_slug: @slug,
+            anchor_id: anchor_id
+          )
+        end
+
+        %(<span id="#{anchor_id}">#{display_text}</span>)
+      end
+    end
+
     def rewrite_image_paths(html)
       html.gsub(/(<img\s[^>]*src=")([^"]+)(")/) do
         prefix = $1

data/lib/ligarb/cli.rb

@@ -296,6 +296,21 @@ module Ligarb
         Footnote IDs are scoped per chapter to avoid collisions in the single-page
         output.
 
+        == Index ==
+
+        Mark terms for the book index using Markdown link syntax with #index:
+
+            [Ruby](#index)                           Index the link text as-is
+            [dynamic typing](#index:動的型付け)       Index under a specific term
+            [Ruby](#index:Ruby,Languages/Ruby)       Multiple index entries (comma-separated)
+            [Ruby](#index:Languages/Ruby)            Hierarchical: Languages > Ruby
+
+        The link is rendered as plain text in the output (no link styling).
+        An "Index" section is automatically appended at the end of the book,
+        with terms sorted alphabetically and grouped by first character.
+
+        Clicking an index entry navigates to the exact location in the chapter.
+
         == Custom CSS ==
 
         Add a 'style' field to book.yml to inject custom CSS:
@@ -330,6 +345,62 @@ module Ligarb
         Each chapter will show a "View on GitHub" link pointing to:
         {repository}/blob/HEAD/{path-from-git-root}
 
+        == Admonitions ==
+
+        GFM-style blockquote alerts are converted to styled admonition boxes.
+        Five types are supported: NOTE, TIP, WARNING, CAUTION, IMPORTANT.
+
+        Syntax:
+
+            > [!NOTE]
+            > This is a note.
+
+            > [!TIP]
+            > Helpful advice here.
+
+            > [!WARNING]
+            > Be careful about this.
+
+            > [!CAUTION]
+            > Dangerous operation.
+
+            > [!IMPORTANT]
+            > Critical information.
+
+        Each type renders with a distinct color and icon:
+        - NOTE: blue (info)
+        - TIP: green (lightbulb)
+        - WARNING: yellow (warning)
+        - CAUTION: red (stop)
+        - IMPORTANT: purple (exclamation)
+
+        == Cross-References ==
+
+        Link to other chapters or headings using standard Markdown relative links.
+        ligarb resolves .md file references to internal anchors in the single-page
+        output.
+
+        Syntax:
+
+            [link text](other-chapter.md)            Link to a chapter
+            [link text](other-chapter.md#Heading)    Link to a specific heading
+            [](other-chapter.md)                     Auto-fill with chapter title
+            [](other-chapter.md#Heading)             Auto-fill with heading text
+
+        The .md path is resolved relative to the current Markdown file's directory.
+        The heading fragment is matched against heading IDs (case-insensitive,
+        normalized the same way heading slugs are generated).
+
+        When the link text is empty, ligarb fills it with the target's display text:
+        - Chapter link: the chapter's display title (e.g. "3. Config Guide")
+        - Heading link: the heading's display text (e.g. "3.2 Setup")
+
+        If a referenced chapter or heading does not exist, the build fails with an
+        error message indicating the broken reference and its source file.
+
+        External URLs ending in .md (e.g. https://example.com/README.md) are not
+        affected — only relative paths are resolved.
+
         == Previous/Next Navigation ==
 
         Each chapter displays Previous and Next navigation links at the bottom.

data/lib/ligarb/template.rb

@@ -12,7 +12,7 @@ module Ligarb
       @css_path      = File.join(ASSETS_DIR, "style.css")
     end
 
-    def render(config:, chapters:, structure:, assets:)
+    def render(config:, chapters:, structure:, assets:, index_entries: [])
       css = File.read(@css_path)
       template = File.read(@template_path)
 
@@ -31,8 +31,72 @@ module Ligarb
       b.local_variable_set(:assets, assets)
       b.local_variable_set(:repository, config.repository)
       b.local_variable_set(:appendix_label, config.appendix_label)
+      b.local_variable_set(:index_tree, build_index_tree(index_entries, chapters))
 
       ERB.new(template, trim_mode: "-").result(b)
     end
+
+    private
+
+    # Build a sorted tree structure for the index.
+    # Returns: { "A" => [ { term: "Algorithm", refs: [...] },
+    #                      { term: "Array", refs: [...], children: [ { term: "sort", refs: [...] } ] } ],
+    #            ... }
+    def build_index_tree(entries, chapters)
+      return {} if entries.empty?
+
+      chapter_titles = chapters.each_with_object({}) { |ch, h| h[ch.slug] = ch.display_title }
+
+      # Group by full term, collecting refs
+      term_refs = {}
+      entries.each do |e|
+        parts = e.term.split("/", 2)
+        top = parts[0]
+        sub = parts[1]
+
+        key = sub ? [top, sub] : [top]
+        term_refs[key] ||= []
+        term_refs[key] << { chapter_slug: e.chapter_slug,
+                            chapter_title: chapter_titles[e.chapter_slug] || e.chapter_slug,
+                            anchor_id: e.anchor_id }
+      end
+
+      # Build nested structure grouped by first character
+      nested = {}
+      term_refs.each do |key, refs|
+        top = key[0]
+        sub = key[1]
+
+        nested[top] ||= { refs: [], children: {} }
+        if sub
+          nested[top][:children][sub] ||= []
+          nested[top][:children][sub].concat(refs)
+        else
+          nested[top][:refs].concat(refs)
+        end
+      end
+
+      # Group by first character and sort
+      grouped = {}
+      nested.sort_by { |k, _| k }.each do |term, data|
+        letter = first_letter(term)
+        grouped[letter] ||= []
+        children = data[:children].sort_by { |k, _| k }.map { |k, v| { term: k, refs: v } }
+        grouped[letter] << { term: term, refs: data[:refs], children: children }
+      end
+
+      grouped
+    end
+
+    def first_letter(term)
+      ch = term[0]
+      if ch&.match?(/[a-zA-Z]/)
+        ch.upcase
+      elsif ch&.match?(/\p{Hiragana}|\p{Katakana}/)
+        ch
+      else
+        ch || "#"
+      end
+    end
   end
 end

data/lib/ligarb/version.rb

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

data/templates/book.html.erb

@@ -103,6 +103,11 @@
       </li>
         <%- end -%>
       <%- end -%>
+      <%- unless index_tree.empty? -%>
+      <li class="toc-chapter" data-chapter="__index__">
+        <a href="#__index__" class="toc-h1" onclick="showChapter('__index__')"><%= language == 'ja' ? '索引' : 'Index' %></a>
+      </li>
+      <%- end -%>
     </ul>
   </nav>
 </div>
@@ -132,11 +137,35 @@
     <%- end -%>
   </section>
   <%- end -%>
+  <%- unless index_tree.empty? -%>
+  <section class="chapter index-chapter" id="chapter-__index__" style="display: none;">
+    <h1><%= language == 'ja' ? '索引' : 'Index' %></h1>
+    <%- index_tree.keys.sort.each do |letter| -%>
+    <div class="index-group">
+      <h2 class="index-letter"><%= letter %></h2>
+      <dl class="index-entries">
+        <%- index_tree[letter].each do |item| -%>
+        <dt><%= item[:term] %></dt>
+        <%- item[:refs].each do |ref| -%>
+        <dd><a href="#<%= ref[:anchor_id] %>" onclick="showChapterAndScroll('<%= ref[:chapter_slug] %>', '<%= ref[:anchor_id] %>'); return false;"><%= ref[:chapter_title] %></a></dd>
+        <%- end -%>
+        <%- item[:children].each do |child| -%>
+        <dt class="index-sub"><%= child[:term] %></dt>
+        <%- child[:refs].each do |ref| -%>
+        <dd class="index-sub"><a href="#<%= ref[:anchor_id] %>" onclick="showChapterAndScroll('<%= ref[:chapter_slug] %>', '<%= ref[:anchor_id] %>'); return false;"><%= ref[:chapter_title] %></a></dd>
+        <%- end -%>
+        <%- end -%>
+        <%- end -%>
+      </dl>
+    </div>
+    <%- end -%>
+  </section>
+  <%- end -%>
 </main>
 
 <script>
 (function() {
-  var chapters = [<%= chapters.map { |c| "\"#{c.slug}\"" }.join(", ") %>];
+  var chapters = [<%= chapters.map { |c| "\"#{c.slug}\"" }.join(", ") %><%= ', "__index__"' unless index_tree.empty? %>];
   var currentChapter = null;
 
   function showChapter(slug) {
@@ -163,6 +192,26 @@
     if (searchInput && searchInput.value) {
       highlightContent(searchInput.value);
     }
+
+    // Render mermaid/KaTeX in newly visible chapter if not yet rendered
+    renderSpecialBlocks(slug);
+  }
+
+  function renderSpecialBlocks(slug) {
+    var section = document.getElementById('chapter-' + slug);
+    if (!section) return;
+    if (typeof mermaid !== 'undefined') {
+      var unrendered = section.querySelectorAll('.mermaid:not([data-processed])');
+      if (unrendered.length > 0) mermaid.run({nodes: unrendered});
+    }
+    if (typeof katex !== 'undefined') {
+      section.querySelectorAll('.math-block[data-math]').forEach(function(el) {
+        if (el.childNodes.length === 0) {
+          try { katex.render(el.getAttribute('data-math'), el, {displayMode: true, throwOnError: false}); }
+          catch(e) { el.textContent = el.getAttribute('data-math'); }
+        }
+      });
+    }
   }
 
   function showChapterAndScroll(slug, headingId) {
@@ -188,6 +237,18 @@
       return;
     }
 
+    // Check for footnote links (fn: or fnref:)
+    var fnMatch = hash.match(/^(?:fn|fnref):(.+?)--/);
+    if (fnMatch) {
+      var fnChSlug = fnMatch[1];
+      if (chapters.indexOf(fnChSlug) !== -1) {
+        if (currentChapter !== fnChSlug) showChapter(fnChSlug);
+        var fnTarget = document.getElementById(hash);
+        if (fnTarget) fnTarget.scrollIntoView({ behavior: 'smooth' });
+        return;
+      }
+    }
+
     // Check for deep link (chapter--heading)
     var parts = hash.split('--');
     if (parts.length >= 2) {
@@ -302,9 +363,36 @@
     localStorage.setItem('ligarb-theme', next);
   });
 
-  // Expose to onclick handlers
+  // Footnote link click handler — scroll within current chapter without triggering chapter switch
+  document.addEventListener('click', function(e) {
+    var link = e.target.closest('a[href^="#fn:"], a[href^="#fnref:"]');
+    if (!link) return;
+    var targetId = link.getAttribute('href').substring(1);
+    var target = document.getElementById(targetId);
+    if (target) {
+      e.preventDefault();
+      history.replaceState(null, '', '#' + targetId);
+      target.scrollIntoView({ behavior: 'smooth' });
+    }
+  });
+
+  // Add title attribute to footnote references for hover preview
+  document.querySelectorAll('sup a[href^="#fn:"]').forEach(function(link) {
+    var targetId = link.getAttribute('href').substring(1);
+    var footnoteLi = document.getElementById(targetId);
+    if (footnoteLi) {
+      // Clone to strip the back-reference link, then get text
+      var clone = footnoteLi.cloneNode(true);
+      var backlinks = clone.querySelectorAll('a[href^="#fnref:"]');
+      backlinks.forEach(function(bl) { bl.remove(); });
+      link.title = clone.textContent.trim();
+    }
+  });
+
+  // Expose to onclick handlers and external scripts
   window.showChapter = showChapter;
   window.showChapterAndScroll = showChapterAndScroll;
+  window.renderSpecialBlocks = function() { if (currentChapter) renderSpecialBlocks(currentChapter); };
 
   // Initialize
   handleHash();
@@ -319,17 +407,12 @@
 <script src="js/mermaid.min.js"></script>
 <script>
 mermaid.initialize({startOnLoad: false});
-mermaid.run({querySelector: '.mermaid'});
+renderSpecialBlocks();
 </script>
 <%- end -%>
 <%- if assets.need?(:katex) -%>
 <script src="js/katex.min.js"></script>
-<script>
-document.querySelectorAll('.math-block').forEach(function(el) {
-  try { katex.render(el.getAttribute('data-math'), el, {displayMode: true, throwOnError: false}); }
-  catch(e) { el.textContent = el.getAttribute('data-math'); }
-});
-</script>
+<script>renderSpecialBlocks();</script>
 <%- end -%>
 </body>
 </html>

metadata

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