canon 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74adcfa8d9b6ab7cc95fba2557dcfecbfa0dbd134e90497a30195fb476de6b42
-  data.tar.gz: dab1ef7a6c5fe852b6935561ddb85e2ffdde6edf4463b36cbe2f9deb5251b4f2
+  metadata.gz: 24f79ae4b9b6817104e388a5bef96d24677f797db5d13bd6f009a26a04170137
+  data.tar.gz: 3b8260af8e2157f2f449421b3d40649521ba64495a15f7667e64c3e343b6d3b7
 SHA512:
-  metadata.gz: 98b8e102b110e5a85363a3ccceb28ffb87082f9695ad0c39b182a1f9f3bca7fc652c471a2134cc621b84d9acfaa858f10aea5c9ddb6a90f5e098ed5b3cd795c5
-  data.tar.gz: 1db527549bde5c60b0f45a8d34a59c877ed9b880a9ea80f076b2501319886e1300d036fd5502820d361d06d9a4957a9b648d479aaf98dcf0bc55bb26f9673066
+  metadata.gz: 971daa53fd96c5c46b5c37c2175f12875e7e36f658cc4186848f1df90ab3db9ceff06af69320e5004d1da1d6b2dc4b35d800c5aca1b1522ac05cf14c73025c21
+  data.tar.gz: 02f5160a42bf651db2a252909966cbc7dea43239cbbae2a53d155c55c4e09709eddc34e599496bfc5cda14705931f24efbebd267b9acc8700b834fb859d8096f

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-12-22 03:34:50 UTC using RuboCop version 1.81.7.
+# on 2026-01-20 02:18:38 UTC using RuboCop version 1.81.7.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -12,34 +12,32 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'spec/canon/comparison/multiple_differences_spec.rb'
-
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleAlignWith.
 # SupportedStylesAlignWith: either, start_of_block, start_of_line
 Layout/BlockAlignment:
   Exclude:
-    - 'lib/canon/diff_formatter/by_line/html_formatter.rb'
-    - 'spec/canon/diff/diff_node_mapper_granularity_spec.rb'
+    - 'spec/canon/rspec_matchers_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 Layout/BlockEndNewline:
   Exclude:
-    - 'spec/canon/diff/diff_node_mapper_granularity_spec.rb'
+    - 'spec/canon/rspec_matchers_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment.
+Layout/CommentIndentation:
+  Exclude:
+    - 'lib/canon/comparison/xml_comparator.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 Layout/ElseAlignment:
   Exclude:
-    - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
+    - 'lib/canon/comparison/xml_comparator.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -47,34 +45,24 @@ Layout/ElseAlignment:
 # SupportedStylesAlignWith: keyword, variable, start_of_line
 Layout/EndAlignment:
   Exclude:
-    - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
+    - 'lib/canon/comparison/xml_comparator.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
-Layout/ExtraSpacing:
-  Exclude:
-    - 'lib/canon/commands/diff_command.rb'
-
-# Offense count: 3
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: normal, indented_internal_methods
+Layout/IndentationConsistency:
   Exclude:
-    - 'spec/canon/comparison/multiple_differences_spec.rb'
+    - 'lib/canon/comparison/xml_comparator.rb'
 
 # Offense count: 4
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Width, AllowedPatterns.
 Layout/IndentationWidth:
   Exclude:
-    - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
-    - 'spec/canon/diff/diff_node_mapper_granularity_spec.rb'
+    - 'spec/canon/rspec_matchers_spec.rb'
 
-# Offense count: 654
+# Offense count: 655
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -83,31 +71,17 @@ Layout/LineLength:
 
 # Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: final_newline, final_blank_line
-Layout/TrailingEmptyLines:
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented
+Layout/MultilineOperationIndentation:
   Exclude:
-    - 'spec/canon/commands/diff_command_spec.rb'
-    - 'spec/canon/comparison/multiple_differences_spec.rb'
-    - 'spec/canon/diff/diff_classifier_spec.rb'
+    - 'lib/canon/diff/diff_classifier.rb'
 
-# Offense count: 10
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'spec/canon/comparison/multiple_differences_spec.rb'
-
-# Offense count: 46
+# Offense count: 48
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
 
-# Offense count: 2
-Lint/DuplicateMethods:
-  Exclude:
-    - 'lib/canon/diff_formatter/by_line/html_formatter.rb'
-
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowComments.
@@ -132,63 +106,58 @@ Lint/UnreachableCode:
   Exclude:
     - 'lib/canon/diff_formatter/debug_output.rb'
 
-# Offense count: 7
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
 # NotImplementedExceptions: NotImplementedError
 Lint/UnusedMethodArgument:
   Exclude:
-    - 'lib/canon/comparison/match_options.rb'
+    - 'lib/canon/diff/path_builder.rb'
     - 'lib/canon/diff_formatter/by_line/base_formatter.rb'
     - 'lib/canon/diff_formatter/by_line/xml_formatter.rb'
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
 
-# Offense count: 219
+# Offense count: 194
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 27
+# Offense count: 20
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 84
 
-# Offense count: 2
-# Configuration parameters: CountBlocks, CountModifierForms.
-Metrics/BlockNesting:
-  Max: 4
-
-# Offense count: 180
+# Offense count: 164
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 347
+# Offense count: 346
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 107
+  Max: 110
 
-# Offense count: 23
+# Offense count: 45
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 142
+# Offense count: 131
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
-# Offense count: 29
+# Offense count: 28
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
   Exclude:
     - 'lib/canon/comparison/xml_comparator.rb'
+    - 'lib/canon/comparison/xml_comparator/attribute_comparator.rb'
     - 'lib/canon/xml/namespace_handler.rb'
-    - 'scripts/investigate_all_false_positives.rb'
 
-# Offense count: 2
+# Offense count: 1
 # Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
 # NamePrefix: is_, has_, have_, does_
 # ForbiddenPrefixes: is_, has_, have_, does_
@@ -197,7 +166,6 @@ Naming/MethodParameterName:
 Naming/PredicatePrefix:
   Exclude:
     - 'lib/canon/comparison/html_comparator.rb'
-    - 'lib/canon/comparison/xml_comparator.rb'
 
 # Offense count: 2
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
@@ -207,21 +175,20 @@ Naming/VariableNumber:
   Exclude:
     - 'lib/canon/comparison/json_comparator.rb'
 
-# Offense count: 4
+# Offense count: 2
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
   Exclude:
     - 'lib/canon/comparison/html_comparator.rb'
-    - 'lib/canon/diff_formatter/diff_detail_formatter.rb'
     - 'lib/canon/xml/xml_base_handler.rb'
 
-# Offense count: 58
+# Offense count: 64
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 24
+# Offense count: 25
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -232,7 +199,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 592
+# Offense count: 663
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 67
@@ -246,7 +213,7 @@ RSpec/ExpectActual:
     - 'spec/canon/rspec_matchers_spec.rb'
     - 'spec/canon/string_matcher_spec.rb'
 
-# Offense count: 171
+# Offense count: 175
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
 RSpec/IndexedLet:
   Exclude:
@@ -269,12 +236,11 @@ RSpec/InstanceVariable:
   Exclude:
     - 'spec/canon/rspec_matchers_spec.rb'
 
-# Offense count: 16
+# Offense count: 15
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: have_received, receive
 RSpec/MessageSpies:
   Exclude:
-    - 'spec/canon/comparison/yaml_comparator_spec.rb'
     - 'spec/canon/diff/diff_classifier_spec.rb'
     - 'spec/canon_spec.rb'
     - 'spec/xml_c14n_spec.rb'
@@ -284,11 +250,11 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 489
+# Offense count: 515
 RSpec/MultipleExpectations:
   Max: 15
 
-# Offense count: 66
+# Offense count: 69
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 13
@@ -302,7 +268,7 @@ RSpec/NamedSubject:
     - 'spec/canon/pretty_printer/json_spec.rb'
     - 'spec/canon/pretty_printer/xml_spec.rb'
 
-# Offense count: 29
+# Offense count: 37
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
@@ -330,14 +296,16 @@ RSpec/SpecFilePathFormat:
     - 'spec/canon/yaml/formatter_spec.rb'
     - 'spec/xml_c14n_spec.rb'
 
-# Offense count: 68
+# Offense count: 95
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Exclude:
+    - 'spec/canon/comparison/whitespace_sensitivity_spec.rb'
     - 'spec/canon/diff/diff_classifier_spec.rb'
+    - 'spec/canon/diff/path_builder_spec.rb'
     - 'spec/canon/tree_diff/operation_converter_spec.rb'
 
-# Offense count: 1
+# Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
 # SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
@@ -346,7 +314,7 @@ RSpec/VerifiedDoubles:
 # AllowedMethods: lambda, proc, it
 Style/BlockDelimiters:
   Exclude:
-    - 'spec/canon/diff/diff_node_mapper_granularity_spec.rb'
+    - 'spec/canon/rspec_matchers_spec.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
@@ -354,7 +322,7 @@ Style/BlockDelimiters:
 # SupportedStyles: empty, nil, both
 Style/EmptyElse:
   Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter.rb'
+    - 'lib/canon/comparison/xml_comparator.rb'
 
 # Offense count: 3
 # Configuration parameters: MinBranchesCount.
@@ -363,10 +331,11 @@ Style/HashLikeCase:
     - 'lib/canon/diff/diff_block_builder.rb'
     - 'lib/canon/xml/character_encoder.rb'
 
-# Offense count: 4
+# Offense count: 6
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/IdenticalConditionalBranches:
   Exclude:
+    - 'lib/canon/comparison/xml_comparator.rb'
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
     - 'lib/canon/diff_formatter/legend.rb'
 
@@ -377,18 +346,26 @@ Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/canon/diff_formatter/debug_output.rb'
 
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: Mode.
-Style/StringConcatenation:
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
   Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter.rb'
+    - 'spec/canon/rspec_matchers_spec.rb'
 
-# Offense count: 6
+# Offense count: 5
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleForMultiline.
 # SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
 Style/TrailingCommaInArguments:
   Exclude:
-    - 'lib/canon/commands/diff_command.rb'
-    - 'spec/canon/commands/diff_command_spec.rb'
+    - 'spec/canon/rspec_matchers_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInHashLiteral:
+  Exclude:
+    - 'spec/canon/rspec_matchers_spec.rb'

data/README.adoc

@@ -69,7 +69,7 @@ Canon::PrettyPrinter::Xml.new(indent: 2).format(xml_input)
 require 'canon/comparison'
 
 xml1 = '<root><a>1</a><b>2</b></root>'
-xml2 = '<root>  <b>2</b>  <a>1</a>  </root>'
+xml2 = '<root>  <a>1</a>  <b>2</b>    </root>'
 
 Canon::Comparison.equivalent?(xml1, xml2)
 # => true (semantically equivalent despite formatting differences)
@@ -534,14 +534,14 @@ Each dimension can have one of three behaviors:
 ====
 ----
 # Default (strict mode): whitespace differences are normative
-xml1 = '<root><p>Hello world</p></root>'
-xml2 = '<root><p>Hello\nworld</p></root>'
+xml1 = "<root><p>Hello world</p></root>"
+xml2 = "<root><p>Hello   \nworld</p></root>"
 Canon::Comparison.equivalent?(xml1, xml2)  # => false
 
 # Normalize mode: whitespace-only differences are formatting-only
 Canon::Comparison.equivalent?(xml1, xml2,
-  match: { text_content: :normalize, structural_whitespace: :normalize }
-)  # => true
+  match: { text_content: :normalize }
+) # => true
 ----
 ====
 
@@ -620,11 +620,11 @@ html1 = '<div><!-- comment --><p>Text</p></div>'
 html2 = '<div><p>Text</p></div>'
 
 # HTML defaults: comments are ignored (presentational)
-result = Canon::Comparison.equivalent?(html1, html2)
+result = Canon::Comparison.equivalent?(html1, html2, format: :html)
 # => true (comments don't affect HTML equivalence by default)
 
 # Explicit strict matching
-result = Canon::Comparison.equivalent?(html1, html2,
+result = Canon::Comparison.equivalent?(html1, html2, format: :html,
   match: { comments: :strict }
 )
 # => false (comments now affect equivalence)
@@ -638,17 +638,17 @@ don't affect the semantic meaning unless explicitly configured to `:strict`.
 ====
 [source,ruby]
 ----
-html1 = '<pre>Line 1\n  Line 2</pre>'
-html2 = '<pre>Line 1\nLine 2</pre>'
+html1 = "<pre>Line 1\n  Line 2</pre>"
+html2 = "<pre>Line 1\nLine 2</pre>"
 
 # Whitespace is preserved in <pre> elements
-result = Canon::Comparison.equivalent?(html1, html2)
+result = Canon::Comparison::HtmlComparator.equivalent?(html1, html2)
 # => false (whitespace differs in pre element)
 
 # But normalized in other elements
-html3 = '<div>Text    with    spaces</div>'
-html4 = '<div>Text with spaces</div>'
-result = Canon::Comparison.equivalent?(html3, html4)
+html3 = "<div>Text    with\n    spaces</div>"
+html4 = "<div>Text with\n spaces</div>"
+result = Canon::Comparison::HtmlComparator.equivalent?(html3, html4)
 # => true (whitespace normalized in regular elements)
 ----
 

data/docs/.lycheeignore

@@ -0,0 +1,69 @@
+# Lychee ignore patterns
+# These link types are valid but lychee can't verify them
+
+# Ignore all .adoc files (source files that don't exist in built site)
+\.adoc$
+
+# Ignore all .html files with inconsistent paths
+\.html$
+
+# Ignore all file:// URLs (link checker has inconsistent base URL handling for local files)
+file://
+
+# Ignore assets directory (CSS/JS files)
+file://.*/assets/.*
+
+# Ignore directory links with trailing slashes (web servers handle these with index.html)
+file://.*/canon/$
+file://.*/canon/.*/$
+file://.*/docs/$
+file://.*/docs/.*/$
+
+# Ignore all /canon/* and /docs/* paths (may have inconsistent base URLs during link checking)
+file://.*/canon/.*
+file://.*/docs/.*
+
+# Ignore asciidoc-style directory links without .html extension
+file://.*/extending-canon$
+file://.*/verbose-mode-architecture$
+file://.*/cli/diff-command$
+file://.*/cli/format-command$
+file://.*/rspec/matchers$
+file://.*/ruby-api/comparison$
+file://.*/ruby-api/formatting$
+file://.*/core-concepts$
+file://.*/installation$
+file://.*/quick-start$
+file://.*/profiles$
+file://.*/comparison-pipeline$
+file://.*/migrating-from-xmldiff$
+file://.*/performance-optimization$
+file://.*/testing-xml-generation$
+file://.*/debugging-test-failures$
+file://.*/choosing-configuration$
+file://.*/guides/choosing-configuration$
+file://.*/environment-configuration/size-limits$
+file://.*/environment-configuration/override-system$
+file://.*/environment-configuration/input-validation$
+file://.*/architecture$
+
+# Ignore example domain links (these don't exist)
+http://a\.com/.*
+http://b\.com/.*
+http://c\.com/.*
+http://example\.com/.*
+http://ns\.com/.*
+http://shop\.com/.*
+http://z\.com/.*
+
+# Ignore GitHub-specific links
+https://github\.com/[^/]+/[^/]+/edit/.*
+https://github\.com/[^/]+/[^/]+/blob/.*
+
+# Ignore mailto links
+mailto:.*
+
+# Ignore localhost links for development
+http://localhost:.*
+http://127\.0\.0\.1:.*
+http://0\.0\.0\.0:.*

data/docs/Gemfile

@@ -6,4 +6,5 @@ gem "just-the-docs"
 
 group :jekyll_plugins do
   gem "jekyll-seo-tag"
+  gem "jekyll-sitemap"
 end

data/docs/_config.yml

@@ -12,8 +12,13 @@ repository: lutaml/canon
 
 # Theme
 theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs@v0.7.0
 color_scheme: light
 
+# Logo (uncomment if you have a logo)
+# logo: "/assets/images/logo.svg"
+# favicon_ico: "/assets/images/favicon.ico"
+
 # AsciiDoc support
 asciidoc: {}
 asciidoctor:
@@ -63,10 +68,36 @@ heading_anchors: true
 # Footer
 footer_content: 'Copyright &copy; 2025 Ribose. Distributed under the <a href="https://github.com/lutaml/canon/blob/main/LICENSE.txt">BSD 2-Clause License</a>.'
 
+# Footer last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Enable code copy button
+enable_copy_code_button: true
+
+# Callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
 # Plugins
 plugins:
   - jekyll-asciidoc
   - jekyll-seo-tag
+  - jekyll-sitemap
 
 # Markdown settings (for any markdown files)
 markdown: kramdown
@@ -75,6 +106,60 @@ kramdown:
   hard_wrap: false
   syntax_highlighter: rouge
 
+# Collections for organizing content
+collections:
+  # Core documentation pages (getting-started, interfaces, etc.)
+  pages:
+    permalink: "/:path/"
+    output: true
+
+  # Feature documentation
+  features:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Understanding/internal documentation
+  understanding:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Advanced topics
+  advanced:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Guides (task-oriented tutorials)
+  guides:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Reference documentation
+  reference:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Just the Docs collection configuration
+just_the_docs:
+  collections:
+    pages:
+      name: Pages
+      nav_fold: false
+    features:
+      name: Features
+      nav_fold: true
+    understanding:
+      name: Understanding
+      nav_fold: true
+    advanced:
+      name: Advanced
+      nav_fold: true
+    guides:
+      name: Guides
+      nav_fold: true
+    reference:
+      name: Reference
+      nav_fold: true
+
 # Defaults
 defaults:
   - scope:
@@ -83,6 +168,10 @@ defaults:
     values:
       layout: default
 
+# Include additional files
+include:
+  - "*.adoc"
+
 # Exclude from processing
 exclude:
   - Gemfile
@@ -97,4 +186,4 @@ exclude:
   - .git
   - .gitignore
 
-permalink: pretty
+permalink: pretty