fix rag heading from code (#25)

Author: mensfeld

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.9.1 (2025-10-17)
+- [Fix] Fixed HeadingTransformer incorrectly treating hash symbols in code blocks as headings.
+  - Now properly tracks code block boundaries (fenced with ``` or ~~~)
+  - Skips heading processing for lines inside code blocks
+  - Prevents Ruby/Python/Shell comments from being interpreted as markdown headings
+  - Added comprehensive test coverage for code block handling
+
 ## 0.9.0 (2025-10-17)
 - [Feature] **No AI Version Detection** - The `compare` command now detects when websites don't serve AI-optimized versions.
   - Triggers when reduction is <5% (nearly identical content for human and AI User-Agents)

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    llm-docs-builder (0.9.0)
+    llm-docs-builder (0.9.1)
       zeitwerk (~> 2.6)
 
 GEM

lib/llm_docs_builder/transformers/heading_transformer.rb

@@ -38,8 +38,18 @@ def transform(content, options = {})
         separator = options[:heading_separator] || ' / '
         heading_stack = []
         lines = content.lines
+        in_code_block = false
 
         transformed_lines = lines.map do |line|
+          # Track code block boundaries (fenced code blocks with ``` or ~~~)
+          if line.match?(/^```|^~~~/)
+            in_code_block = !in_code_block
+            next line
+          end
+
+          # Skip heading processing if inside code block
+          next line if in_code_block
+
           # Match markdown headings (1-6 hash symbols followed by space and text)
           heading_match = line.match(/^(#+)\s+(.+)$/)
 

lib/llm_docs_builder/version.rb

@@ -2,5 +2,5 @@
 
 module LlmDocsBuilder
   # Current version of the LlmDocsBuilder gem
-  VERSION = '0.9.0'
+  VERSION = '0.9.1'
 end

spec/transformers/heading_transformer_spec.rb

@@ -145,6 +145,29 @@
         expect(result).to include('## API Reference / Authentication & Authorization')
         expect(result).to include('### API Reference / Authentication & Authorization / Using API Keys (OAuth2)')
       end
+
+      it 'ignores hash symbols in code blocks' do
+        content = <<~MD
+          # Configuration
+          ## Consumer Settings
+
+          ```ruby
+          # This is a Ruby comment
+          config.timeout = 30
+          # Another comment
+          ```
+
+          ### auto_offset_reset
+        MD
+
+        result = transformer.transform(content, options)
+
+        expect(result).to include('# Configuration')
+        expect(result).to include('## Configuration / Consumer Settings')
+        expect(result).to include('### Configuration / Consumer Settings / auto_offset_reset')
+        expect(result).to include('# This is a Ruby comment')
+        expect(result).to include('# Another comment')
+      end
     end
 
     context 'when content has no headings' do