ligarb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cc0976cad1fb731ff5ad56f38d7ee7142a0deecc158b70482f017df2611b678
-  data.tar.gz: 802ec24c33f96792addf6939cf92e04e7163e1b6864958dbfef7b8a02d224645
+  metadata.gz: c88870d66d05c780d5dd46b93ebad2f0daffa3ce201d8a51b6cec8c61eedcb73
+  data.tar.gz: 3044c7b204c390fe1ed67f187598d50164e27d917e82dae9897878c0d418f334
 SHA512:
-  metadata.gz: 58807bf5f3088e399d395761e75e65d52933db36ce116326e30a88b0ccb87425d4cde2644c89912e10b772f5565238b15384ada2fdd2ea261509eceded09ab97
-  data.tar.gz: 36069084a2b167996bf2310aa2bd17ee0689d59b52941fbb295b2c623eeb3f34e24a8ccd95bb12751ce23782c9df1374f3c8df8eaa46d24742f63beed146ec87
+  metadata.gz: 8f1f24fa71f51560116db5ee1390701988e2640ed17dd4680124aad7c1f59ae82d9f513379ed38de3f8b187874399c41322f6649ea588b205e50ae760087bc62
+  data.tar.gz: 927eb04a33dcc3b24525a5899a412f852d2a0f872c6422b0034d881ed67ba27c0151b602e01d42ebf7900324ad3f4d9392d6b7843abc9ac472d9e707466b618c

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

@@ -22,8 +22,16 @@ module Ligarb
       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")

data/lib/ligarb/chapter.rb

@@ -5,10 +5,11 @@ require "kramdown-parser-gfm"
 
 module Ligarb
   class Chapter
-    attr_reader :title, :slug, :html, :headings, :number, :appendix_letter
+    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
@@ -60,7 +61,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
 
@@ -139,12 +143,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,35 @@ 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)
+
         == 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.2.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.2.0
 platform: ruby
 authors:
 - ligarb contributors