canon 0.3.27 → 0.3.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8de5d7008a348037ef44fdd8bd5ee722e8077e058ab1e53cd2995b0dd5f0e2c
-  data.tar.gz: 930b0efd7c7302968a6ff2f4fd9af8a6261a1a57fc71707d9206333a380f47a8
+  metadata.gz: ff4b9d6b5a57176d2d382f7b0d730047161920dfb4cb4004b58d60bba9c0edab
+  data.tar.gz: ed8dfddca4d957fbc3fbb1e62dbd1b03032c661e82c06513304d2abcf4e288cc
 SHA512:
-  metadata.gz: 570bd7072c65d9c87316becd43334255bb176ee4260c1d40738cd51ee3d030c4ea3df9d93e923a2f6062c493271fb122bb252e1f41c6c0e40836d7fbe675fd5b
-  data.tar.gz: a7d60c235f74cdf466a35b4ef6204c9943d306a1167dead26123314326936f90f7d96a5d2ee3bd2ace308556655c2e6492d2beb2ebab25933d4ce796dfd84e9f
+  metadata.gz: 778faacee321541b7d8ceef7c3497969080243acd01fc01bde3902deb68b7664e5ed966a230fc969766cfb32aefe76c81be9d7ae8a86d6b0f0ea870a6ed32cf1
+  data.tar.gz: a3a42291c8100b20362c273c34778abdb4f22eec057c616e54daa60b77e4272c9fe5742fa352874ffc1145c0800e89f6c00800d8938bfcf2af364cff9c71ba9f

data/.rubocop.yml

@@ -17,3 +17,5 @@ plugins:
 
 AllCops:
   TargetRubyVersion: 3.0
+  Exclude:
+    - "spec/fixtures/**/*"

data/README.adoc

@@ -189,6 +189,9 @@ $ canon help
 * **link:docs/CHARACTER_VISUALIZATION[Character visualization]** -
   Whitespace and special characters
 * **link:docs/INPUT_VALIDATION[Input validation]** - Error handling
+* **link:docs/features/regenerate-expected[Regenerating expected heredocs]** -
+  `CANON_REGENERATE_EXPECTED=true` to rewrite failing `be_*_equivalent_to`
+  heredocs in-place from the prettyprinted received value
 
 === Advanced topics
 

data/docs/INDEX.adoc

@@ -140,4 +140,4 @@ See link:contributing[Contributing to Documentation]
 * Configuration profiles with element-level whitespace classification
 * Three-way whitespace sensitivity: strict, normalize, insensitive
 
-See link:https://github.com/lutaml/canon/blob/main/CHANGELOG.md[Full Changelog]
+See link:https://github.com/lutaml/canon/releases[Full Changelog]

data/docs/advanced/diff-classification.adoc

@@ -279,7 +279,7 @@ direction relative to the partner content: `before`, `after`, or
   re-alignment walk encounters an asymmetric whitespace node
 * **Report-only** — does not change equivalence outcomes compared to
   pre-#137 behaviour; only changes the diff-report shape (see
-  link:../features/diff-formatting/whitespace-adjacency.adoc[Whitespace
+  link:../../features/diff-formatting/whitespace-adjacency/[Whitespace
   adjacency] for details)
 
 .Example: Comment handling

data/docs/advanced/extending-canon.adoc

@@ -188,6 +188,6 @@ See the source code for examples of:
 
 == See Also
 
-* link:../understanding/architecture.adoc[Architecture] - 4-layer architecture overview
+* link:../../understanding/architecture/[Architecture] - 4-layer architecture overview
 * link:../features/diff-formatting/[Diff Formatting] - Layer 4 rendering options
 * link:diff-pipeline[Comparison Pipeline] - Technical pipeline details

data/docs/advanced/index.adoc

@@ -19,10 +19,10 @@ This section provides detailed technical information about Canon's internal algo
 
 == What You'll Learn
 
-link:dom-diff-internals[**DOM Diff Internals**]::
+link:../understanding/algorithms/dom-diff/[**DOM Diff**]::
 Deep dive into Canon's default DOM diff algorithm: position-based matching, operation detection, and diff generation.
 
-link:semantic-tree-diff-internals[**Semantic Tree Diff Internals**]::
+link:../understanding/algorithms/semantic-tree-diff/[**Semantic Tree Diff**]::
 How the experimental semantic tree diff works: signature calculation, similarity matching, and operation classification.
 
 link:verbose-mode-architecture[**Verbose Mode Architecture**]::
@@ -57,7 +57,7 @@ The DOM diff algorithm is Canon's stable, well-tested comparison strategy.
 * Performance is critical
 * Stable, predictable behavior required
 
-See link:dom-diff-internals[DOM Diff Internals] for implementation details.
+See link:../understanding/algorithms/dom-diff/[DOM Diff] for implementation details.
 
 === Semantic Tree Diff Algorithm
 
@@ -77,7 +77,7 @@ The semantic tree diff is an experimental algorithm that understands document st
 * Operation-based analysis desired
 * Willing to accept experimental status
 
-See link:semantic-tree-diff-internals[Semantic Tree Diff Internals] for implementation details.
+See link:../understanding/algorithms/semantic-tree-diff/[Semantic Tree Diff Internals] for implementation details.
 
 == Architecture Patterns
 
@@ -203,8 +203,8 @@ result = Canon::Comparison.compare(doc1, doc2,
 
 == Next Steps
 
-* Read link:dom-diff-internals[DOM Diff Internals] to understand the default algorithm
-* Explore link:semantic-tree-diff-internals[Semantic Tree Diff] for advanced matching
+* Read link:../understanding/algorithms/dom-diff/[DOM Diff] to understand the default algorithm
+* Explore link:../understanding/algorithms/semantic-tree-diff/[Semantic Tree Diff] for advanced matching
 * Check link:extending-canon[Extending Canon] to add custom functionality
 
 == See Also

data/docs/advanced/verbose-mode-architecture.adoc

@@ -498,6 +498,6 @@ This ensures the correct output order and separation of concerns.
 == See also
 
 * link:../features/diff-formatting/[Diff Formatting] - Diff output customization
-* link:../understanding/comparison-pipeline.adoc[Comparison Pipeline] - 4-layer architecture
+* link:../../understanding/comparison-pipeline/[Comparison Pipeline] - 4-layer architecture
 * link:../interfaces/rspec/[RSpec Matchers] - Using verbose mode in tests
 * link:../interfaces/cli/[CLI] - Command-line verbose mode

data/docs/features/configuration-profiles.adoc

@@ -280,11 +280,11 @@ Profile YAML keys map directly to Canon configuration accessors:
 |===
 
 All `DiffConfig` and `MatchConfig` attributes documented in
-link:../reference/options-across-interfaces.adoc[Options Across Interfaces]
+link:../../reference/options-across-interfaces/[Options Across Interfaces]
 are supported.
 
 == See also
 
-* link:environment-configuration/override-system.adoc[Override System] -- ENV variable priority
-* link:match-options/index.adoc[Match Options] -- match profile presets (`:strict`, `:spec_friendly`, etc.)
-* link:../guides/choosing-configuration.adoc[Choosing Configuration] -- decision guide
+* link:../environment-configuration/override-system/[Override System] -- ENV variable priority
+* link:../match-options/[Match Options] -- match profile presets (`:strict`, `:spec_friendly`, etc.)
+* link:../../guides/choosing-configuration/[Choosing Configuration] -- decision guide

data/docs/features/diff-formatting/algorithm-specific-output.adoc

@@ -525,9 +525,9 @@ result = Canon::Comparison.equivalent?(doc1, doc2,
 
 == See Also
 
-* link:index.adoc[Diff Formatting Overview]
-* link:diff-modes.adoc[Diff Modes] - by_line vs by_object details
-* link:../match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] - How algorithms work
+* link:../[Diff Formatting Overview]
+* link:../diff-formatting/[Diff modes] - by_line vs by_object details
+* link:../../match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] - How algorithms work
 * link:../../understanding/algorithms/[Algorithms] - Detailed algorithm documentation
-* link:colors-and-symbols.adoc[Colors and Symbols] - Visual formatting options
-* link:../../guides/choosing-configuration.adoc[Choosing Configuration] - Decision guide
+* link:../colors-and-symbols/[Colors and Symbols] - Visual formatting options
+* link:../../../guides/choosing-configuration/[Choosing Configuration] - Decision guide

data/docs/features/diff-formatting/colors-and-symbols.adoc

@@ -480,7 +480,7 @@ Canon supports multiple color themes that adapt the diff display to your termina
 * `:retro` -- Amber CRT, low blue light, accessibility
 * `:claude` -- Claude Code diff style with red/green backgrounds
 
-See link:themes.adoc[Diff display themes] for full theme documentation.
+See link:../themes/[Diff display themes] for full theme documentation.
 
 === Automatic Color Detection
 
@@ -727,9 +727,9 @@ The combination ensures diffs are readable even without color perception.
 
 == Related Features
 
-* link:display-filtering.adoc[Display Filtering] - Control which diff types to show
-* link:context-and-grouping.adoc[Context and Grouping] - Control surrounding context
-* link:../match-options/index.adoc[Match Options] - Configure what's considered normative vs informative
+* link:../display-filtering/[Display Filtering] - Control which diff types to show
+* link:../context-and-grouping/[Context and Grouping] - Control surrounding context
+* link:../../match-options/[Match Options] - Configure what's considered normative vs informative
 
 == See Also
 

data/docs/features/diff-formatting/comment-asymmetry.adoc

@@ -88,7 +88,7 @@ DIFFERENCE #1 — comments: Comment present on EXPECTED only:
 == Combined with whitespace asymmetry
 
 The same realignment walk handles asymmetric whitespace-only text
-nodes (link:whitespace-adjacency.adoc[issue #137]) and asymmetric
+nodes (link:../whitespace-adjacency/[issue #137]) and asymmetric
 comment nodes together. When a children mismatch is fully explained by
 a combination of asymmetric whitespace and asymmetric comments, the
 walker emits one diff per asymmetric node with the appropriate
@@ -147,9 +147,9 @@ Both comparison paths delegate to `ChildRealignment.walk`:
 
 == Related
 
-* link:whitespace-adjacency.adoc[Whitespace adjacency] — sibling
+* link:../whitespace-adjacency/[Whitespace adjacency] — sibling
   contract for asymmetric whitespace-only text nodes.
-* link:../../advanced/diff-classification.adoc[Diff classification] —
+* link:../../../advanced/diff-classification/[Diff classification] —
   Normative vs informative differences.
 
 == History

data/docs/features/diff-formatting/display-filtering.adoc

@@ -507,10 +507,10 @@ puts result.differences.count  # Number of informative diffs
 
 == See also
 
-* link:../match-options/index.adoc[Match options] - Configure match dimensions
-* link:colors-and-symbols.adoc[Colors and symbols] - Understanding diff
+* link:../../match-options/[Match options] - Configure match dimensions
+* link:../colors-and-symbols/[Colors and symbols] - Understanding diff
   visualization
-* link:../../../understanding/algorithms/index.adoc[Diff algorithms] -
+* link:../../../understanding/algorithms/[Diff algorithms] -
   Algorithm-specific behavior
-* link:../../../advanced/diff-classification.adoc[Diff classification] -
+* link:../../../advanced/diff-classification/[Diff classification] -
   Normative vs informative classification

data/docs/features/diff-formatting/display-preprocessing.adoc

@@ -11,7 +11,7 @@ nav_order: 6
 
 Display preprocessing controls how documents are normalized *before the
 line-by-line diff is rendered*. It is entirely separate from
-link:../../features/match-options/index.adoc[comparison preprocessing]
+link:../../match-options/[comparison preprocessing]
 (`FormatConfig#preprocessing`), which controls normalization for equivalence
 detection.
 
@@ -588,7 +588,7 @@ solve an asymmetric formatting problem: fixture files are typically
 hand-indented heredocs, while received XML is compact.
 
 For the full rationale, algorithm, and examples see the dedicated guide:
-link:../match-options/pretty-printed-fixtures.adoc[Pretty-printed fixture support].
+link:../../match-options/pretty-printed-fixtures/[Pretty-printed fixture support].
 
 === Quick reference
 
@@ -644,13 +644,13 @@ described in <<_controlling_whitespace_visualization_with_element_classification
 
 == See also
 
-* link:character-visualization.adoc[Character visualization] — how special
+* link:../character-visualization/[Character visualization] — how special
   characters are rendered in diff output
-* link:../match-options/pretty-printed-fixtures.adoc[Pretty-printed fixture support]
+* link:../../match-options/pretty-printed-fixtures/[Pretty-printed fixture support]
   — full rationale, algorithm, and walkthrough examples
-* link:../../reference/options-across-interfaces.adoc[Options across interfaces]
+* link:../../../reference/options-across-interfaces/[Options across interfaces]
   — Layer 1b display preprocessing table
-* link:../../reference/environment-variables.adoc[Environment variables] —
+* link:../../../reference/environment-variables/[Environment variables] —
   `CANON_DISPLAY_PREPROCESSING` etc.
-* link:../match-options/index.adoc[Match options] — comparison preprocessing
+* link:../../match-options/[Match options] — comparison preprocessing
   (`cfg.xml.preprocessing`)

data/docs/features/diff-formatting/index.adoc

@@ -32,7 +32,7 @@ Canon's diff formatting includes:
   themselves instead of cascading into mismatches against neighbouring
   content. The Reason line names the direction relative to the partner
   (`before`/`after`/`adjacent to`)
-  (link:./whitespace-adjacency.adoc[details])
+  (link:whitespace-adjacency/[details])
 
 == Available formatting options
 
@@ -45,7 +45,7 @@ determination.
 * Show only normative differences (affect equivalence)
 * Show only informative differences (don't affect equivalence)
 
-See link:display-filtering.adoc[Display filtering] for complete details.
+See link:display-filtering/[Display filtering] for complete details.
 
 === Colors and symbols
 
@@ -56,7 +56,7 @@ Canon uses color-coded output to distinguish different types of changes:
 * Yellow: Normative structural changes
 * Cyan: Informative differences
 
-See link:colors-and-symbols.adoc[Colors and symbols] for details.
+See link:colors-and-symbols/[Colors and symbols] for details.
 
 === Diff display themes
 
@@ -67,7 +67,7 @@ Choose from 4 predefined color themes (light, dark, retro, claude) or create cus
 * Retro theme: Amber CRT, low blue light
 * Claude theme: Maximum contrast with colored backgrounds
 
-See link:themes.adoc[Themes] for complete theme documentation.
+See link:themes/[Themes] for complete theme documentation.
 
 === Character visualization
 
@@ -90,7 +90,7 @@ Canon::Config.configure do |cfg|
 end
 ----
 
-See link:character-visualization.adoc[Character visualization] for details.
+See link:character-visualization/[Character visualization] for details.
 
 === Context and grouping
 
@@ -99,7 +99,7 @@ Control how much surrounding context to show:
 * Context lines: Number of unchanged lines around changes
 * Grouping: Combine nearby changes into single blocks
 
-See link:context-and-grouping.adoc[Context and grouping] for details.
+See link:context-and-grouping/[Context and grouping] for details.
 
 === Display preprocessing
 
@@ -111,7 +111,7 @@ algorithm:
 * `:pretty_print` — run through `Canon::PrettyPrinter::Xml` (one tag per line)
 * `:c14n` — run through XML C14N normalization
 
-See link:display-preprocessing.adoc[Display preprocessing] for details,
+See link:display-preprocessing/[Display preprocessing] for details,
 including the character-visualization constraint for future extensibility.
 
 === Pretty-diff mode
@@ -133,7 +133,7 @@ formatter = Canon::DiffFormatter.new(
 )
 ----
 
-See link:pretty-diff-mode.adoc[Pretty-diff mode] for details and limitations.
+See link:pretty-diff-mode/[Pretty-diff mode] for details and limitations.
 
 === Algorithm-specific output
 
@@ -142,7 +142,7 @@ Different diff algorithms produce different output styles:
 * DOM diff: Line-by-line or by-object output
 * Semantic tree diff: Operation-based output with tree structure
 
-See link:algorithm-specific-output.adoc[Algorithm-specific output] for details.
+See link:algorithm-specific-output/[Algorithm-specific output] for details.
 
 == Common use cases
 
@@ -189,16 +189,16 @@ Diff formatting can be configured:
 * Per-format (XML, HTML, JSON, YAML)
 * Per-operation via method parameters
 
-See link:../../reference/cli-options.adoc[CLI options] and
-link:../../interfaces/ruby-api/index.adoc[Ruby API] for configuration details.
+See link:../../reference/cli-options/[CLI options] and
+link:../../interfaces/ruby-api/[Ruby API] for configuration details.
 
 == See also
 
-* link:../../understanding/comparison-pipeline.adoc[Comparison pipeline] -
+* link:../../understanding/comparison-pipeline/[Comparison pipeline] -
   Understanding the diff generation process
-* link:../match-options/index.adoc[Match options] - Controlling what gets
+* link:../match-options/[Match options] - Controlling what gets
   compared
-* link:../../advanced/diff-classification.adoc[Diff classification] -
+* link:../../advanced/diff-classification/[Diff classification] -
   Normative vs informative differences
-* link:../../interfaces/cli/index.adoc[CLI interface] - Command-line usage
-* link:../../interfaces/ruby-api/index.adoc[Ruby API] - Programmatic usage
+* link:../../interfaces/cli/[CLI interface] - Command-line usage
+* link:../../interfaces/ruby-api/[Ruby API] - Programmatic usage

data/docs/features/diff-formatting/pretty-diff-mode.adoc

@@ -94,7 +94,7 @@ For preformatted elements where every whitespace character is significant, use
 `preserve_whitespace_elements` instead (e.g. `%w[pre code]`).
 
 See
-link:display-preprocessing.adoc#_controlling_whitespace_visualization_with_element_classification[display-preprocessing:
+link:../display-preprocessing/#_controlling_whitespace_visualization_with_element_classification[display-preprocessing:
 element classification] for the full three-way classification system and HTML
 format defaults.
 
@@ -146,9 +146,9 @@ to avoid resolving against `Canon::Diff` which is an unrelated internal module.
 
 == See also
 
-* link:display-preprocessing.adoc[Display preprocessing] — normalising input
+* link:../display-preprocessing/[Display preprocessing] — normalising input
   before the diff
-* link:context-and-grouping.adoc[Context and grouping] — context_lines and
+* link:../context-and-grouping/[Context and grouping] — context_lines and
   diff grouping
-* link:display-filtering.adoc[Display filtering] — normative/informative
+* link:../display-filtering/[Display filtering] — normative/informative
   filtering (`:by_line` only)

data/docs/features/diff-formatting/themes.adoc

@@ -347,7 +347,7 @@ Colors `:bright_black` and `:bright_white` are not supported by Rainbow in 16-co
 
 == See also
 
-* link:colors-and-symbols.adoc[Colors and symbols] - Diff markers and classification
-* link:display-filtering.adoc[Display filtering] - Control which diff types appear
+* link:../colors-and-symbols/[Colors and symbols] - Diff markers and classification
+* link:../display-filtering/[Display filtering] - Control which diff types appear
 * link:../environment-configuration/index.html[Environment configuration] - ENV variable setup
 * link:../../reference/environment-variables.html[Environment variables reference] - Complete variable listing

data/docs/features/diff-formatting/whitespace-adjacency.adoc

@@ -110,7 +110,7 @@ information. In that case Canon falls back to naming the parent
 element instead — `Whitespace inside <PARENT>` — and the
 Expected/Actual detail block renders each side's parent element
 compactly per the contract from
-link:../../advanced/semantic-diff-report.adoc#parent-context-fallback-for-ambiguous-text-diffs[issue #112].
+link:../../../advanced/semantic-diff-report/#parent-context-fallback-for-ambiguous-text-diffs[issue #112].
 
 NOTE: An earlier wording (`Whitespace surrounding "X"`) classified the
 *whitespace node's position among its own siblings* rather than its
@@ -212,9 +212,9 @@ whitespace node as a single normative `:whitespace_adjacency` diff.
 
 == Related
 
-* link:../../advanced/diff-classification.adoc[Diff classification] —
+* link:../../../advanced/diff-classification/[Diff classification] —
   Normative vs informative differences.
-* link:../match-options/index.adoc[Match options] — Configuring
+* link:../../match-options/[Match options] — Configuring
   `preserve_whitespace_elements`, `collapse_whitespace_elements`, and
   `strip_whitespace_elements`.
 

data/docs/features/environment-configuration/index.adoc

@@ -120,7 +120,7 @@ export CANON_DIFF_THEME=claude
 
 Valid values: `light`, `dark`, `retro`, `claude`
 
-See link:../diff-formatting/themes.adoc[Diff display themes] for complete theme documentation.
+See link:../diff-formatting/themes/[Diff display themes] for complete theme documentation.
 
 === Context and grouping
 
@@ -162,7 +162,7 @@ Valid values: `true`, `false`, `1`, `0`, `yes`, `no`
 
 Canon provides configurable size limits to prevent hangs or excessive resource usage when processing very large files.
 
-See link:size-limits.adoc[Size Limits] for detailed configuration.
+See link:size-limits/[Size Limits] for detailed configuration.
 
 Key variables:
 
@@ -172,7 +172,7 @@ Key variables:
 
 == Override system
 
-See link:override-system.adoc[Override System] for how environment variables interact with programmatic configuration.
+See link:override-system/[Override System] for how environment variables interact with programmatic configuration.
 
 == Usage across interfaces
 
@@ -307,7 +307,7 @@ export CANON_USE_COLOR=false
 
 == Complete variable reference
 
-See link:../../reference/environment-variables.adoc[Environment Variables Reference] for a complete table of all environment variables.
+See link:../../reference/environment-variables/[Environment Variables Reference] for a complete table of all environment variables.
 
 == Troubleshooting
 
@@ -344,7 +344,7 @@ puts "Source of algorithm: #{resolver.source_for(:algorithm)}"
 
 == See also
 
-* link:size-limits.adoc[Size Limits] - File size and node count limits
-* link:override-system.adoc[Override System] - How ENV vars override defaults
-* link:../../reference/environment-variables.adoc[Environment Variables Reference] - Complete variable listing
-* link:../../reference/options-across-interfaces.adoc[Options Across Interfaces] - How options map across CLI, Ruby, and RSpec
+* link:size-limits/[Size Limits] - File size and node count limits
+* link:override-system/[Override System] - How ENV vars override defaults
+* link:../../reference/environment-variables/[Environment Variables Reference] - Complete variable listing
+* link:../../reference/options-across-interfaces/[Options Across Interfaces] - How options map across CLI, Ruby, and RSpec

data/docs/features/environment-configuration/override-system.adoc

@@ -43,7 +43,7 @@ Configuration values are resolved using a strict four-level priority:
 
 **Rule**: Higher priority always wins, regardless of when values are set.
 
-See link:../configuration-profiles.adoc[Configuration Profiles] for details on the profile layer.
+See link:../../configuration-profiles/[Configuration Profiles] for details on the profile layer.
 
 == How overrides work
 
@@ -437,7 +437,7 @@ end
 
 == See also
 
-* link:index.adoc[Environment Configuration] - Overview and usage
-* link:size-limits.adoc[Size Limits] - Limit-specific ENV variables
-* link:../../reference/environment-variables.adoc[Environment Variables Reference] - Complete listing
-* link:../../reference/options-across-interfaces.adoc[Options Across Interfaces] - How options work in CLI, Ruby, RSpec
+* link:../[Environment Configuration] - Overview and usage
+* link:../size-limits/[Size Limits] - Limit-specific ENV variables
+* link:../../../reference/environment-variables/[Environment Variables Reference] - Complete listing
+* link:../../../reference/options-across-interfaces/[Options Across Interfaces] - How options work in CLI, Ruby, RSpec

data/docs/features/environment-configuration/size-limits.adoc

@@ -267,7 +267,7 @@ export CANON_VERBOSE_DIFF=false
 
 == See also
 
-* link:index.adoc[Environment Configuration] - Complete ENV configuration
-* link:override-system.adoc[Override System] - How ENV vars work
-* link:../../reference/environment-variables.adoc[Environment Variables Reference] - All variables
-* link:../../understanding/algorithms/dom-diff.adoc[DOM Algorithm] - Faster for large files
+* link:../[Environment Configuration] - Complete ENV configuration
+* link:../override-system/[Override System] - How ENV vars work
+* link:../../../reference/environment-variables/[Environment Variables Reference] - All variables
+* link:../../../understanding/algorithms/dom-diff/[DOM Algorithm] - Faster for large files

data/docs/features/index.adoc

@@ -79,7 +79,7 @@ Customize how differences are displayed.
 
 === Configuration Profiles
 
-link:configuration-profiles.adoc[**Configuration Profiles**]::
+link:configuration-profiles/[**Configuration Profiles**]::
 Bundle all settings into named presets defined in YAML.
 +
 * Built-in profiles (metanorma, metanorma_debug)

data/docs/features/match-options/algorithm-specific-behavior.adoc

@@ -357,9 +357,9 @@ end
 
 == See Also
 
-* link:index.adoc[Match Options Overview]
+* link:../[Match Options Overview]
 * link:../../understanding/algorithms/[Algorithms] - Detailed algorithm documentation
-* link:dimensions.adoc[Match Dimensions] - All available dimensions
-* link:profiles.adoc[Match Profiles] - Preset configurations
-* link:../diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output] - How output differs
-* link:../../guides/choosing-configuration.adoc[Choosing Configuration] - Decision guide
+* link:../match-options/[Match dimensions] - All available dimensions
+* link:../match-options/[Match profiles] - Preset configurations
+* link:../../diff-formatting/algorithm-specific-output/[Algorithm-Specific Output] - How output differs
+* link:../../../guides/choosing-configuration/[Choosing Configuration] - Decision guide

data/docs/features/match-options/html-policies.adoc

@@ -314,4 +314,4 @@ See the following files for implementation details:
 
 * link:index.html[Match Options] - Overview of match system
 * link:algorithm-specific-behavior.html[Algorithm-Specific Behavior] - How algorithms handle options
-* link:../../advanced/diff-classification.html[Diff Classification] - Normative vs informative
+* link:../../../advanced/diff-classification/[Diff Classification] - Normative vs informative

data/docs/features/match-options/index.adoc

@@ -12,7 +12,7 @@ has_children: true
 
 This section provides a complete reference for Canon's match options, including match dimensions, behaviors, and predefined profiles.
 
-Match options control **Layer 3 (Match Options)** of Canon's 4-layer comparison architecture. See link:../../understanding/comparison-pipeline.adoc[Comparison Pipeline] for the complete flow.
+Match options control **Layer 3 (Match Options)** of Canon's 4-layer comparison architecture. See link:../../understanding/comparison-pipeline/[Comparison Pipeline] for the complete flow.
 
 == Overview
 
@@ -22,15 +22,15 @@ Match options control which aspects of documents are compared and how strictly t
 * **Dimension behaviors**: How each dimension is compared (`:strict`, `:normalize`, `:ignore`)
 * **Match profiles**: Predefined combinations for common scenarios
 
-**Important**: Match options behave differently with each algorithm. See link:algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] for details.
+**Important**: Match options behave differently with each algorithm. See link:algorithm-specific-behavior/[Algorithm-Specific Behavior] for details.
 
 == Child Pages
 
-* link:dimensions.adoc[Match Dimensions] - Detailed reference for all dimensions
-* link:profiles.adoc[Match Profiles] - Predefined configurations
-* link:algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] - How DOM and Semantic algorithms interpret options differently
-* link:html-policies.adoc[HTML-Specific Policies] - HTML format-specific comparison policies
-* link:pretty-printed-fixtures.adoc[Pretty-Printed Fixture Support] - Comparing compact generated XML against hand-indented fixture heredocs without spurious whitespace differences
+* link:../match-options/[Match dimensions] - Detailed reference for all dimensions
+* link:../match-options/[Match profiles] - Predefined configurations
+* link:algorithm-specific-behavior/[Algorithm-Specific Behavior] - How DOM and Semantic algorithms interpret options differently
+* link:html-policies/[HTML-Specific Policies] - HTML format-specific comparison policies
+* link:pretty-printed-fixtures/[Pretty-Printed Fixture Support] - Comparing compact generated XML against hand-indented fixture heredocs without spurious whitespace differences
 
 == Match dimensions overview
 

data/docs/features/match-options/pretty-printed-fixtures.adoc

@@ -261,10 +261,10 @@ new code.
 
 == See also
 
-* link:../../features/diff-formatting/display-preprocessing.adoc[Display preprocessing]
+* link:../../diff-formatting/display-preprocessing/[Display preprocessing]
   — the `display_preprocessing` option and `XmlNormalized` serializer
-* link:index.adoc[Match options overview] — whitespace sensitivity classification
-* link:../../reference/options-across-interfaces.adoc[Options across interfaces]
+* link:../[Match options overview] — whitespace sensitivity classification
+* link:../../../reference/options-across-interfaces/[Options across interfaces]
   — cross-interface reference table
-* link:../../reference/environment-variables.adoc[Environment variables]
+* link:../../../reference/environment-variables/[Environment variables]
   — `CANON_XML_DIFF_PRETTY_PRINTED_EXPECTED`, `CANON_XML_DIFF_PRETTY_PRINTED_RECEIVED`