feat: Add explanation document type to Diataxis framework

.diataxis

@@ -2,5 +2,6 @@
   "readme": "docs/README.md",
   "howtos": "docs/how-to",
   "tutorials": "docs/tutorials",
+  "explanations": "docs/explanations",
   "adr": "docs/exp/adr"
-}
+}

README.md

@@ -6,6 +6,7 @@ Diataxis is a command-line tool for managing documentation following the [Diatax
 
 * Create How-To guides with proper formatting and naming conventions
 * Create tutorials with consistent structure
+* Create explanation documents following the Diataxis framework
 * Automatically update README.md with links to documentation
 * Smart title formatting that converts statements to "How to" format
 * Maintains alphabetical order in documentation lists
@@ -34,6 +35,9 @@ dia howto new "Configure SSL certificates"              # or use an imperative s
 # Create a New Tutorial
 dia tutorial new "Getting Started with Docker"
 
+# Create a New Explanation
+dia explanation new "Why We Use PostgreSQL"
+
 # Create a new ADR
 dia adr new "Do whiteboard wednesday talks"
 ```

docs/README.md

@@ -9,7 +9,7 @@
 ### HowTos
 
 <!-- howtolog -->
-* [How to manually Test All Diataxis Features](how-to/how_to_manually_test_all_diataxis_features.md)
+* [How to manually test all diataxis features](how-to/how_to_manually_test_all_diataxis_features.md)
 <!-- howtologstop -->
 
 ### Tutorials
@@ -25,3 +25,9 @@
 * [ADR-0002](exp/adr/0002-use-configuration-file-for-document-paths.md) - Use Configuration File for Document Paths
 * [ADR-0003](exp/adr/0003-auto-generate-readme-with-document-links.md) - Auto-Generate README with Document Links
 <!-- adrlogstop -->
+
+### Explanations
+
+<!-- explanationlog -->
+
+<!-- explanationlogstop -->

docs/how-to/how_to_manually_test_all_diataxis_features.md

@@ -1,11 +1,11 @@
-# How to Manually Test All Diataxis Features
+# How to manually test all diataxis features
 
 ## Description
 
 The diataxis gem provides several key features that need testing:
 
 * Configuration management via `.diataxis` file
-* Document creation (how-tos, tutorials, ADRs)
+* Document creation (how-tos, tutorials, explanations, ADRs)
 * Document renaming based on title changes
 * README generation and updates
 * Directory structure maintenance
@@ -87,6 +87,17 @@ bundle exec dia adr new "Use PostgreSQL Database"
 # - Uses correct template and numbering
 ```
 
+#### Test Explanation Creation
+
+```bash
+bundle exec dia explanation new "Why We Use This Architecture"
+
+# Expected:
+# - Creates explanation_why_we_use_this_architecture.md
+# - Updates README.md with link
+# - Uses correct template with Overview, Background, Key Concepts, etc.
+```
+
 ### 3. Document Title Changes
 
 #### Test How-to Title Update

lib/diataxis/cli.rb

@@ -21,6 +21,8 @@ def self.run(args)
         handle_tutorial(args)
       when 'adr'
         handle_adr(args)
+      when 'explanation'
+        handle_explanation(args)
       when 'update'
         handle_update(args)
       else
@@ -37,6 +39,7 @@ def self.usage
       puts '  howto new "Title"     - Create a new how-to guide'
       puts '  tutorial new "Title"  - Create a new tutorial'
       puts '  adr new "Title"      - Create a new architectural decision record'
+      puts '  explanation new "Title" - Create a new explanation document'
       puts '  update <directory>    - Update document filenames and README.md'
       exit 1
     end
@@ -48,6 +51,7 @@ def self.handle_init(args)
         'readme' => 'docs/README.md',
         'howtos' => 'docs/how-to',
         'tutorials' => 'docs/tutorials',
+        'explanations' => 'docs/explanations',
         'adr' => 'docs/exp/adr'
       }
       Config.create(directory, config)
@@ -68,7 +72,7 @@ def self.handle_howto(args)
       HowTo.new(title, howto_dir).create
 
       # Update the README.md after creating a new how-to
-      document_types = [HowTo, Tutorial]
+      document_types = [HowTo, Tutorial, Explanation]
       ReadmeManager.new(directory, document_types).update
     end
 
@@ -87,7 +91,7 @@ def self.handle_tutorial(args)
       Tutorial.new(title, tutorial_dir).create
 
       # Update the README.md after creating a new tutorial
-      document_types = [HowTo, Tutorial]
+      document_types = [HowTo, Tutorial, Explanation]
       ReadmeManager.new(directory, document_types).update
     end
 
@@ -120,11 +124,30 @@ def self.handle_update(args)
       abort("Error: '#{directory}' is not a valid directory.") unless Dir.exist?(directory)
 
       Config.load(directory)
-      document_types = [HowTo, Tutorial, ADR]
+      document_types = [HowTo, Tutorial, Explanation, ADR]
 
       # First collect all files and update filenames
       readme_manager = ReadmeManager.new(directory, document_types)
       readme_manager.update
     end
+
+    def self.handle_explanation(args)
+      if args.length < 2 || args[0] != 'new'
+        puts 'Usage: diataxis explanation new "Title of the Explanation"'
+        exit 1
+      end
+      directory = Dir.pwd
+      title = args[1..].join(' ')
+      config = Config.load(directory)
+
+      explanation_dir = File.join(directory, config['explanations'])
+      FileUtils.mkdir_p(explanation_dir)
+
+      Explanation.new(title, explanation_dir).create
+
+      # Update the README.md after creating a new explanation
+      document_types = [HowTo, Tutorial, Explanation]
+      ReadmeManager.new(directory, document_types).update
+    end
   end
 end

lib/diataxis/config.rb

@@ -25,7 +25,7 @@ def self.load(directory = '.')
 
     def self.create(directory = '.', config = DEFAULT_CONFIG)
       config_path = File.join(directory, CONFIG_FILE)
-      File.write(config_path, JSON.pretty_generate(config))
+      File.write(config_path, "#{JSON.pretty_generate(config)}\n")
       puts "Created #{config_path} with default configuration"
     end
 

lib/diataxis/diataxis.rb

@@ -272,6 +272,44 @@ def self.update_filename(filepath, directory)
     end
   end
 
+  # Explanation document type for understanding concepts and background
+  # Follows the Diataxis framework's explanation format
+  class Explanation < Document
+    def self.pattern
+      '**/explanation_*.md'
+    end
+
+    def content
+      <<~CONTENT
+        # #{title}
+
+        ## Overview
+
+        A brief introduction to what this explanation covers.
+
+        ## Background
+
+        Historical context and evolution of the concept/system.
+
+        ## Key Concepts
+
+        Core ideas and principles that help understand the topic.
+
+        ## Technical Context
+
+        How this fits into the broader technical landscape.
+
+        ## Rationale
+
+        Why things are done this way and what trade-offs were considered.
+
+        ## Related Concepts
+
+        Links to related topics and further reading.
+      CONTENT
+    end
+  end
+
   # README management
   class ReadmeManager
     def initialize(directory, document_types)