ligarb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c88870d66d05c780d5dd46b93ebad2f0daffa3ce201d8a51b6cec8c61eedcb73
-  data.tar.gz: 3044c7b204c390fe1ed67f187598d50164e27d917e82dae9897878c0d418f334
+  metadata.gz: 20b29dff31e22937e2ab71a7011d1ed2fb193c8717753c7a23500767645807f1
+  data.tar.gz: be6404f8dccb7cea765b8635f9663b57f0c23e73253a29da6ac49ca0017baae1
 SHA512:
-  metadata.gz: 8f1f24fa71f51560116db5ee1390701988e2640ed17dd4680124aad7c1f59ae82d9f513379ed38de3f8b187874399c41322f6649ea588b205e50ae760087bc62
-  data.tar.gz: 927eb04a33dcc3b24525a5899a412f852d2a0f872c6422b0034d881ed67ba27c0151b602e01d42ebf7900324ad3f4d9392d6b7843abc9ac472d9e707466b618c
+  metadata.gz: 9ca9e973840571772b22b493ddfbc15b87c844abf05e84c2805c3d63ede347a3e245745e5bab2b8d2a3cb8d7b13b3c6c9d94f70b2d5c6d572eefadc11a839d64
+  data.tar.gz: 98f30f871f31b96331ebac03a4e0bb85690e612e14dd0412592ff2a1400a897698807d206f851143561e27bd384d32273517531708c2f1af7ee59aaaedf33c17

data/lib/ligarb/builder.rb

@@ -16,6 +16,7 @@ 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)
@@ -106,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,6 +5,8 @@ require "kramdown-parser-gfm"
 
 module Ligarb
   class Chapter
+    class CrossReferenceError < StandardError; end
+
     attr_reader :title, :slug, :html, :headings, :number, :appendix_letter, :index_entries
     attr_accessor :part_title, :cover, :relative_path
 
@@ -43,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}"
@@ -96,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)

data/lib/ligarb/cli.rb

@@ -374,6 +374,33 @@ module Ligarb
         - 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/version.rb

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

metadata

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