fix: update documentation page slugs to use correct path format and enhance sidebar navigation association

Author: rsmithlal

app/builders/better_together/navigation_builder.rb

@@ -656,7 +656,7 @@ def create_documentation_navigation_item(area, entry, position, parent: nil) # r
         if entry[:type] == :directory
           attributes[:item_type] = 'dropdown'
           if entry[:default_path].present?
-            attributes[:linkable] = documentation_page_for(entry[:title], entry[:default_path])
+            attributes[:linkable] = documentation_page_for(entry[:title], entry[:default_path], area)
           else
             attributes[:url] = '#'
           end
@@ -666,7 +666,7 @@ def create_documentation_navigation_item(area, entry, position, parent: nil) # r
           end
         else
           attributes[:item_type] = 'link'
-          attributes[:linkable] = documentation_page_for(entry[:title], entry[:path])
+          attributes[:linkable] = documentation_page_for(entry[:title], entry[:path], area)
           create_documentation_item_with_context(area, attributes)
         end
       end
@@ -693,9 +693,9 @@ def create_documentation_item_with_context(area, attributes)
         raise ActiveRecord::RecordInvalid.new(e.record), "#{e.message} -- #{attributes.inspect}"
       end
 
-      def documentation_page_for(title, relative_path)
+      def documentation_page_for(title, relative_path, sidebar_nav_area = nil)
         slug = documentation_slug(relative_path)
-        attrs = documentation_page_attributes(title, slug, relative_path)
+        attrs = documentation_page_attributes(title, slug, relative_path, sidebar_nav_area)
         page = ::BetterTogether::Page.i18n.find_by(slug: slug)
 
         if page
@@ -704,16 +704,22 @@ def documentation_page_for(title, relative_path)
           locked_page.reload
           locked_page.assign_attributes(attrs)
           locked_page.save!
+          # Re-set the slug after save in case FriendlyId regenerated it
+          locked_page.update_columns(slug: slug) if locked_page.slug != slug
           locked_page
         else
-          ::BetterTogether::Page.create!(attrs)
+          new_page = ::BetterTogether::Page.create!(attrs)
+          # Re-set the slug after creation in case FriendlyId regenerated it
+          new_page.slug = slug if new_page.slug != slug
+          new_page.save!(validate: false) if new_page.changed?
+          new_page
         end
       end
 
-      def documentation_page_attributes(title, slug, relative_path) # rubocop:todo Metrics/MethodLength
-        {
+      def documentation_page_attributes(title, slug, relative_path, sidebar_nav_area = nil) # rubocop:todo Metrics/MethodLength
+        attrs = {
           title_en: title,
-          slug_en: slug,
+          slug_en: slug, # Set slug directly via Mobility to bypass FriendlyId normalization
           published_at: Time.zone.now,
           privacy: 'public',
           protected: true,
@@ -727,13 +733,19 @@ def documentation_page_attributes(title, slug, relative_path) # rubocop:todo Met
             }
           ]
         }
+
+        # Associate the documentation navigation area as the sidebar nav
+        attrs[:sidebar_nav] = sidebar_nav_area if sidebar_nav_area.present?
+
+        attrs
       end
 
       def documentation_slug(path)
         relative = path.is_a?(Pathname) ? documentation_relative_path(path) : path.to_s
-        base_slug = relative.sub(/\.md\z/i, '').tr('/', '-').parameterize
-        base_slug = 'docs' if base_slug.blank?
-        "docs-#{base_slug}"
+        # Remove .md extension, downcase, and preserve directory structure with slashes
+        base_slug = relative.sub(/\.md\z/i, '').downcase.tr('_', '-')
+        base_slug = 'overview' if base_slug.blank?
+        "docs/#{base_slug}"
       end
 
       def documentation_file_path(relative_path)

spec/builders/better_together/navigation_builder_spec.rb

@@ -212,28 +212,55 @@
       expect(area).to be_present
       expect(area.navigation_items.top_level.count).to eq(2)
 
-      root_file_item = area.navigation_items.find { |item| item.linkable&.slug == 'docs-readme' }
+      root_file_item = area.navigation_items.find { |item| item.linkable&.slug == 'docs/readme' }
       expect(root_file_item).to be_present
       expect(root_file_item.title).to eq('Overview')
       expect(root_file_item.linkable).to be_a(BetterTogether::Page)
       markdown_block = root_file_item.linkable.page_blocks.first.block
       expect(markdown_block).to be_a(BetterTogether::Content::Markdown)
       expect(markdown_block.markdown_file_path).to eq(tmp_docs_root.join('README.md').to_s)
 
-      developers_item = area.navigation_items.find { |item| item.linkable&.slug == 'docs-developers-readme' }
+      developers_item = area.navigation_items.find { |item| item.linkable&.slug == 'docs/developers/readme' }
       expect(developers_item).to be_present
       expect(developers_item.item_type).to eq('dropdown')
-      expect(developers_item.linkable&.slug).to eq('docs-developers-readme')
+      expect(developers_item.linkable&.slug).to eq('docs/developers/readme')
       expect(developers_item.children.count).to eq(3) # README, api, systems directory
 
       systems_dropdown = developers_item.children.find { |child| child.title == 'Systems' }
       expect(systems_dropdown.item_type).to eq('dropdown')
       expect(systems_dropdown.children.count).to eq(1)
       systems_page = systems_dropdown.children.first.linkable
-      expect(systems_page.slug).to eq('docs-developers-systems-caching')
+      expect(systems_page.slug).to eq('docs/developers/systems/caching')
       systems_markdown = systems_page.page_blocks.first.block
       expect(systems_markdown.markdown_file_path).to eq(tmp_docs_root.join('developers/systems/caching.md').to_s)
     end
+
+    it 'assigns the documentation navigation area as sidebar_nav for all documentation pages' do
+      described_class.build_documentation_navigation
+
+      area = BetterTogether::NavigationArea.i18n.find_by(slug: 'documentation')
+      expect(area).to be_present
+
+      # Check root file page
+      root_page = BetterTogether::Page.i18n.find_by(slug: 'docs/readme')
+      expect(root_page).to be_present
+      expect(root_page.sidebar_nav).to eq(area)
+
+      # Check developers guide page
+      developers_page = BetterTogether::Page.i18n.find_by(slug: 'docs/developers/readme')
+      expect(developers_page).to be_present
+      expect(developers_page.sidebar_nav).to eq(area)
+
+      # Check API page
+      api_page = BetterTogether::Page.i18n.find_by(slug: 'docs/developers/api')
+      expect(api_page).to be_present
+      expect(api_page.sidebar_nav).to eq(area)
+
+      # Check nested systems/caching page
+      caching_page = BetterTogether::Page.i18n.find_by(slug: 'docs/developers/systems/caching')
+      expect(caching_page).to be_present
+      expect(caching_page.sidebar_nav).to eq(area)
+    end
   end
 
   describe 'navigation item relationships' do