docyard 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e127990af44c6db555b00cfd2c7a89be408e6e4bfddf2bed9a753387f708ee87
-  data.tar.gz: ed54f92691fe29fc8dd83b8b797504162283bba12840c49c120a4341ac22a66c
+  metadata.gz: 77d317cd25d544eef47b5bdcecb0515b8937da93b347d39cac6fd1f87bb43b19
+  data.tar.gz: bf97d9449013ba8bf370682271990f64b2c2092bfdc9bf0deb99cf2b67056cc2
 SHA512:
-  metadata.gz: 7ae09bfea3ce92e5b5b8cee3e7317d6d57b253e17314adcfbf9f468cc0635a54d3cbd55a90f28807514875359e4d93b4e1c68fee99b7ec65a9ab12d34a21c6c2
-  data.tar.gz: 3c2148376ab27c804a148666795420afe24fe23cb890fa76fa2602af5434d9e60d589fcbb460454210d2dfe1cc38f1f8584db41b1209db14b8b21ec3d7abeb68
+  metadata.gz: 2e30597716798800240f4436c423284d1972fe5fa0abf1de8007b3279dde0a87ef32210cb830c84769c15db0c82e6c372337ae06baaecdb71fa866342c9697a3
+  data.tar.gz: f0ae1edf5937153c9ed3ccb1cc7c599c7f650e16470ad976ef0918c09bc030502ecf89dad6a8a7c79ee8055530b61a65d556bbfd147e08a86349a2475777ee54

data/.rubocop.yml

@@ -22,7 +22,11 @@ Metrics/ClassLength:
   Max: 150
 
 Metrics/MethodLength:
-  Max: 15
+  Max: 16
+
+Metrics/ParameterLists:
+  MaxOptionalParameters: 6
+  CountKeywordArgs: false
 
 Style/Documentation:
   Enabled: false

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-01-13
+
+### Added
+- **Landing Pages** - Hero sections, feature grids, and custom footer layouts for documentation homepages (#45)
+- **Tab Navigation** - Top-level navigation tabs for organizing documentation into sections like Guide, API, Components (#52)
+- **Header CTAs** - Configurable call-to-action buttons in the header with primary/secondary variants (#51)
+- **Breadcrumbs** - Path navigation with auto-truncation for deep nesting and configurable via `navigation.breadcrumbs` (#54)
+- **Doc Page Footer** - Social icons, "Built with Docyard" attribution, and copyright text in TOC column (#55)
+- **Auto-detect Branding** - Automatic logo and favicon detection from `docs/public/` directory (#49)
+- **Social Icon Mapping** - 16 social platform icons with automatic platform-to-icon mapping (#55)
+
+### Changed
+- **Sidebar Overhaul** - Per-section `_sidebar.yml` files, improved collapsible behavior, and better active state handling (#50, #53)
+- **Config Schema** - Reorganized configuration with `branding`, `navigation`, and `socials` sections (#48)
+- **Sidebar Convention** - Section-based sidebar configuration in `docs/<section>/_sidebar.yml` (#47)
+- **UI Refresh** - Updated typography, spacing, and visual consistency across components (#44)
+- **Logo Update** - New logo with cyan accent and dark mode support (#46)
+
 ## [0.7.0] - 2026-01-01
 
 ### Added
@@ -122,7 +140,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial gem structure
 - Project scaffolding
 
-[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/sanifhimani/docyard/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/sanifhimani/docyard/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/sanifhimani/docyard/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/sanifhimani/docyard/compare/v0.4.0...v0.5.0

data/lib/docyard/build/asset_bundler.rb

@@ -35,6 +35,8 @@ module Docyard
         main_css = File.read(File.join(ASSETS_PATH, "css", "main.css"))
         css_content = resolve_css_imports(main_css)
         minified = CSSminify.compress(css_content)
+        minified = fix_calc_whitespace(minified)
+        minified = fix_css_math_functions(minified)
         hash = generate_hash(minified)
 
         write_bundled_asset(minified, hash, "css")
@@ -43,6 +45,19 @@ module Docyard
         hash
       end
 
+      def fix_calc_whitespace(css)
+        css
+          .gsub(/\)\+(?!\s)/, ") + ")
+          .gsub(/\)-(?![-\s])/, ") - ")
+          .gsub(/(\d[a-z]*)\+(?=[\w(])/, '\1 + ')
+          .gsub(/([lch])\+(?=[\d.])/, '\1 + ')
+          .gsub(/([lch])-(?=[\d.])/, '\1 - ')
+      end
+
+      def fix_css_math_functions(css)
+        css.gsub(/\bmax\(0,/, "max(0px,").gsub(/\bmin\(0,/, "min(0px,)")
+      end
+
       def resolve_css_imports(css_content)
         css_content.gsub(/@import url\('([^']+)'\);/) do |match|
           import_file = Regexp.last_match(1)
@@ -92,8 +107,8 @@ module Docyard
       end
 
       def update_html_references(css_hash, js_hash)
-        html_files = Dir.glob(File.join(config.build.output_dir, "**", "*.html"))
-        base_url = normalize_base_url(config.build.base_url)
+        html_files = Dir.glob(File.join(config.build.output, "**", "*.html"))
+        base_url = normalize_base_url(config.build.base)
 
         html_files.each do |file|
           content = replace_asset_references(File.read(file), css_hash, js_hash, base_url)
@@ -104,15 +119,15 @@ module Docyard
       end
 
       def replace_asset_references(content, css_hash, js_hash, base_url)
-        content.gsub(%r{/assets/css/main\.css}, "#{base_url}assets/bundle.#{css_hash}.css")
-          .gsub(%r{/assets/js/theme\.js}, "#{base_url}assets/bundle.#{js_hash}.js")
-          .gsub(%r{/assets/js/components\.js}, "")
-          .gsub(%r{<script src="/assets/js/reload\.js"></script>}, "")
+        content.gsub(%r{/_docyard/css/main\.css}, "#{base_url}_docyard/bundle.#{css_hash}.css")
+          .gsub(%r{/_docyard/js/theme\.js}, "#{base_url}_docyard/bundle.#{js_hash}.js")
+          .gsub(%r{/_docyard/js/components\.js}, "")
+          .gsub(%r{<script src="/_docyard/js/reload\.js"></script>}, "")
       end
 
       def write_bundled_asset(content, hash, extension)
         filename = "bundle.#{hash}.#{extension}"
-        output_path = File.join(config.build.output_dir, "assets", filename)
+        output_path = File.join(config.build.output, "_docyard", filename)
         FileUtils.mkdir_p(File.dirname(output_path))
         File.write(output_path, content)
       end

data/lib/docyard/build/file_copier.rb

@@ -3,6 +3,8 @@
 module Docyard
   module Build
     class FileCopier
+      DOCYARD_OUTPUT_DIR = "_docyard"
+
       attr_reader :config, :verbose
 
       def initialize(config, verbose: false)
@@ -14,7 +16,7 @@ module Docyard
         puts "\nCopying static assets..."
 
         count = 0
-        count += copy_user_assets
+        count += copy_public_files
         count += copy_branding_assets
 
         log "[✓] Copied #{count} static files"
@@ -23,25 +25,22 @@ module Docyard
 
       private
 
-      def copy_user_assets
-        user_assets_dir = "docs/assets"
-        return 0 unless Dir.exist?(user_assets_dir)
-
-        output_assets_dir = File.join(config.build.output_dir, "assets")
-        FileUtils.mkdir_p(output_assets_dir)
+      def copy_public_files
+        public_dir = Constants::PUBLIC_DIR
+        return 0 unless Dir.exist?(public_dir)
 
-        files = find_user_asset_files(user_assets_dir)
-        files.each { |file| copy_single_asset(file, "docs/assets/", output_assets_dir) }
+        files = find_files_in_dir(public_dir)
+        files.each { |file| copy_single_file(file, "#{public_dir}/", config.build.output) }
 
-        log "[✓] Copied #{files.size} user assets from docs/assets/" if files.any?
+        log "[✓] Copied #{files.size} public files from #{public_dir}/" if files.any?
         files.size
       end
 
-      def find_user_asset_files(assets_dir)
-        Dir.glob(File.join(assets_dir, "**", "*")).select { |f| File.file?(f) }
+      def find_files_in_dir(dir)
+        Dir.glob(File.join(dir, "**", "*")).select { |f| File.file?(f) }
       end
 
-      def copy_single_asset(file, prefix, output_dir)
+      def copy_single_file(file, prefix, output_dir)
         relative_path = file.delete_prefix(prefix)
         dest_path = File.join(output_dir, relative_path)
 
@@ -60,26 +59,49 @@ module Docyard
       end
 
       def copy_default_branding_assets
-        templates_assets = File.join(__dir__, "..", "templates", "assets")
-        count = 0
+        templates_assets = templates_assets_path
+        count = copy_branding_files(templates_assets)
+        count + copy_fonts(templates_assets)
+      end
 
-        ["logo.svg", "logo-dark.svg", "favicon.svg"].each do |asset_file|
-          source_path = File.join(templates_assets, asset_file)
-          next unless File.exist?(source_path)
+      def templates_assets_path
+        File.join(__dir__, "..", "templates", "assets")
+      end
 
-          dest_path = File.join(config.build.output_dir, "assets", asset_file)
-          FileUtils.mkdir_p(File.dirname(dest_path))
-          FileUtils.cp(source_path, dest_path)
+      def copy_branding_files(templates_assets)
+        branding_files = %w[logo.svg logo-dark.svg favicon.svg]
+        branding_files.sum { |asset_file| copy_asset_to_docyard(templates_assets, asset_file, "default branding") }
+      end
 
-          log "  Copied default branding: #{asset_file}" if verbose
-          count += 1
-        end
+      def copy_asset_to_docyard(source_dir, filename, label)
+        source_path = File.join(source_dir, filename)
+        return 0 unless File.exist?(source_path)
 
-        count
+        dest_path = File.join(config.build.output, DOCYARD_OUTPUT_DIR, filename)
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        FileUtils.cp(source_path, dest_path)
+        log "  Copied #{label}: #{filename}" if verbose
+        1
+      end
+
+      def copy_fonts(templates_assets)
+        fonts_dir = File.join(templates_assets, "fonts")
+        return 0 unless Dir.exist?(fonts_dir)
+
+        font_files = Dir.glob(File.join(fonts_dir, "*")).select { |f| File.file?(f) }
+        font_files.sum { |font_file| copy_single_font(font_file) }
+      end
+
+      def copy_single_font(font_file)
+        dest_path = File.join(config.build.output, DOCYARD_OUTPUT_DIR, "fonts", File.basename(font_file))
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        FileUtils.cp(font_file, dest_path)
+        log "  Copied font: #{File.basename(font_file)}" if verbose
+        1
       end
 
       def copy_user_branding_assets
-        %w[logo logo_dark favicon].sum { |asset_key| copy_single_branding_asset(asset_key) }
+        %w[logo favicon].sum { |asset_key| copy_single_branding_asset(asset_key) }
       end
 
       def copy_single_branding_asset(asset_key)
@@ -89,7 +111,7 @@ module Docyard
         full_path = File.join("docs", asset_path)
         return 0 unless File.exist?(full_path)
 
-        dest_path = File.join(config.build.output_dir, "assets", asset_path)
+        dest_path = File.join(config.build.output, asset_path)
         FileUtils.mkdir_p(File.dirname(dest_path))
         FileUtils.cp(full_path, dest_path)
 

data/lib/docyard/build/sitemap_generator.rb

@@ -15,7 +15,7 @@ module Docyard
         urls = collect_urls
         sitemap_content = build_sitemap(urls)
 
-        output_path = File.join(config.build.output_dir, "sitemap.xml")
+        output_path = File.join(config.build.output, "sitemap.xml")
         File.write(output_path, sitemap_content)
 
         puts "[✓] Generated sitemap.xml (#{urls.size} URLs)"
@@ -24,10 +24,10 @@ module Docyard
       private
 
       def collect_urls
-        html_files = Dir.glob(File.join(config.build.output_dir, "**", "index.html"))
+        html_files = Dir.glob(File.join(config.build.output, "**", "index.html"))
 
         html_files.map do |file|
-          relative_path = file.delete_prefix(config.build.output_dir).delete_suffix("/index.html")
+          relative_path = file.delete_prefix(config.build.output).delete_suffix("/index.html")
           url_path = relative_path.empty? ? "/" : relative_path
           lastmod = File.mtime(file).utc.iso8601
 
@@ -36,15 +36,15 @@ module Docyard
       end
 
       def build_sitemap(urls)
-        base_url = config.build.base_url
-        base_url = base_url.chop if base_url.end_with?("/")
+        base = config.build.base
+        base = base.chop if base.end_with?("/")
 
         xml = ['<?xml version="1.0" encoding="UTF-8"?>']
         xml << '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
 
         urls.each do |url|
           xml << "  <url>"
-          xml << "    <loc>#{base_url}#{url[:loc]}</loc>"
+          xml << "    <loc>#{base}#{url[:loc]}</loc>"
           xml << "    <lastmod>#{url[:lastmod]}</lastmod>"
           xml << "  </url>"
         end

data/lib/docyard/build/static_generator.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require "tty-progressbar"
+require_relative "../rendering/template_resolver"
+require_relative "../navigation/prev_next_builder"
+require_relative "../navigation/breadcrumb_builder"
 
 module Docyard
   module Build
@@ -10,10 +13,12 @@ module Docyard
       def initialize(config, verbose: false)
         @config = config
         @verbose = verbose
-        @renderer = Renderer.new(base_url: config.build.base_url, config: config)
+        @renderer = Renderer.new(base_url: config.build.base, config: config)
       end
 
       def generate
+        copy_custom_landing_page if custom_landing_page?
+
         markdown_files = collect_markdown_files
         puts "\n[✓] Found #{markdown_files.size} markdown files"
 
@@ -33,24 +38,72 @@ module Docyard
 
       private
 
+      def custom_landing_page?
+        File.file?("docs/index.html")
+      end
+
+      def copy_custom_landing_page
+        output_path = File.join(config.build.output, "index.html")
+        FileUtils.mkdir_p(File.dirname(output_path))
+        FileUtils.cp("docs/index.html", output_path)
+        log "[✓] Copied custom landing page (index.html)"
+      end
+
       def collect_markdown_files
-        Dir.glob(File.join("docs", "**", "*.md"))
+        files = Dir.glob(File.join("docs", "**", "*.md"))
+        files.reject! { |f| f == "docs/index.md" } if custom_landing_page?
+        files
       end
 
       def generate_page(markdown_file_path)
         output_path = determine_output_path(markdown_file_path)
         current_path = determine_current_path(markdown_file_path)
 
-        sidebar_html = build_sidebar(current_path)
-        html_content = renderer.render_file(
-          markdown_file_path,
-          sidebar_html: sidebar_html,
-          branding: branding_options
-        )
+        html_content = render_markdown_file(markdown_file_path, current_path)
+        html_content = apply_search_exclusion(html_content, current_path)
+        write_output(output_path, html_content)
+      end
+
+      def apply_search_exclusion(html_content, current_path)
+        return html_content unless excluded_from_search?(current_path)
+
+        html_content.gsub("data-pagefind-body", "data-pagefind-ignore")
+      end
+
+      def excluded_from_search?(path)
+        exclude_patterns = config.search.exclude || []
+        exclude_patterns.any? do |pattern|
+          next false unless pattern.start_with?("/")
+
+          File.fnmatch(pattern, path, File::FNM_PATHNAME)
+        end
+      end
+
+      def render_markdown_file(markdown_file_path, current_path)
+        markdown = Markdown.new(File.read(markdown_file_path))
+        template_resolver = TemplateResolver.new(markdown.frontmatter, config.data)
+        branding = branding_options
 
+        navigation = build_navigation_html(template_resolver, current_path, markdown, branding[:header_ctas])
+        renderer.render_file(markdown_file_path, **navigation, branding: branding,
+                                                               template_options: template_resolver.to_options,
+                                                               current_path: current_path)
+      end
+
+      def build_navigation_html(template_resolver, current_path, markdown, header_ctas)
+        return { sidebar_html: "", prev_next_html: "", breadcrumbs: nil } unless template_resolver.show_sidebar?
+
+        sidebar_builder = build_sidebar_instance(current_path, header_ctas)
+        {
+          sidebar_html: sidebar_builder.to_html,
+          prev_next_html: build_prev_next(sidebar_builder, current_path, markdown),
+          breadcrumbs: build_breadcrumbs(sidebar_builder.tree, current_path)
+        }
+      end
+
+      def write_output(output_path, html_content)
         FileUtils.mkdir_p(File.dirname(output_path))
         File.write(output_path, html_content)
-
         log "Generated: #{output_path}" if verbose
       end
 
@@ -59,7 +112,7 @@ module Docyard
         base_name = File.basename(relative_path, ".md")
         dir_name = File.dirname(relative_path)
 
-        output_dir = config.build.output_dir
+        output_dir = config.build.output
 
         if base_name == "index"
           File.join(output_dir, dir_name, "index.html")
@@ -80,14 +133,34 @@ module Docyard
         end
       end
 
-      def build_sidebar(current_path)
+      def build_sidebar_instance(current_path, header_ctas = [])
         SidebarBuilder.new(
           docs_path: "docs",
           current_path: current_path,
-          config: config
+          config: config,
+          header_ctas: header_ctas
+        )
+      end
+
+      def build_prev_next(sidebar_builder, current_path, markdown)
+        PrevNextBuilder.new(
+          sidebar_tree: sidebar_builder.tree,
+          current_path: current_path,
+          frontmatter: markdown.frontmatter,
+          config: {}
         ).to_html
       end
 
+      def build_breadcrumbs(sidebar_tree, current_path)
+        return nil unless breadcrumbs_enabled?
+
+        BreadcrumbBuilder.new(sidebar_tree: sidebar_tree, current_path: current_path)
+      end
+
+      def breadcrumbs_enabled?
+        config.navigation.breadcrumbs != false
+      end
+
       def branding_options
         BrandingResolver.new(config).resolve
       end

data/lib/docyard/builder.rb

@@ -35,7 +35,7 @@ module Docyard
     private
 
     def prepare_output_directory
-      output_dir = config.build.output_dir
+      output_dir = config.build.output
 
       if clean && Dir.exist?(output_dir)
         log "[✓] Cleaning #{output_dir}/ directory"
@@ -68,7 +68,7 @@ module Docyard
       sitemap_gen = Build::SitemapGenerator.new(config)
       sitemap_gen.generate
 
-      File.write(File.join(config.build.output_dir, "robots.txt"), robots_txt_content)
+      File.write(File.join(config.build.output, "robots.txt"), robots_txt_content)
       log "[+] Generated robots.txt"
     end
 
@@ -78,14 +78,14 @@ module Docyard
     end
 
     def robots_txt_content
-      base_url = config.build.base_url
-      base_url = "#{base_url}/" unless base_url.end_with?("/")
+      base = config.build.base
+      base = "#{base}/" unless base.end_with?("/")
 
       <<~ROBOTS
         User-agent: *
         Allow: /
 
-        Sitemap: #{base_url}sitemap.xml
+        Sitemap: #{base}sitemap.xml
       ROBOTS
     end
 
@@ -94,7 +94,7 @@ module Docyard
 
       puts "\n#{'=' * 50}"
       puts "Build complete in #{format('%.2f', elapsed)}s"
-      puts "Output: #{config.build.output_dir}/"
+      puts "Output: #{config.build.output}/"
 
       summary = "#{pages} pages, #{bundles} bundles, #{assets} static files"
       summary += ", #{indexed} pages indexed" if indexed.positive?

data/lib/docyard/config/branding_resolver.rb

@@ -6,6 +6,15 @@ module Docyard
       @config = config
     end
 
+    SOCIAL_ICON_MAP = {
+      "x" => "x-logo", "twitter" => "x-logo", "discord" => "discord-logo",
+      "linkedin" => "linkedin-logo", "youtube" => "youtube-logo", "instagram" => "instagram-logo",
+      "facebook" => "facebook-logo", "tiktok" => "tiktok-logo", "twitch" => "twitch-logo",
+      "reddit" => "reddit-logo", "mastodon" => "mastodon-logo", "threads" => "threads-logo",
+      "pinterest" => "pinterest-logo", "medium" => "medium-logo", "slack" => "slack-logo",
+      "gitlab" => "gitlab-logo"
+    }.freeze
+
     def resolve
       return default_branding unless config
 
@@ -23,52 +32,152 @@ module Docyard
         logo: Constants::DEFAULT_LOGO_PATH,
         logo_dark: Constants::DEFAULT_LOGO_DARK_PATH,
         favicon: nil,
-        display_logo: true,
-        display_title: true
+        credits: true,
+        social: []
       }
     end
 
     def config_branding_options
-      site_options.merge(logo_options).merge(search_options).merge(appearance_options)
+      site_options
+        .merge(logo_options)
+        .merge(search_options)
+        .merge(credits_options)
+        .merge(social_options)
+        .merge(navigation_options)
+        .merge(tabs_options)
     end
 
     def site_options
       {
-        site_title: config.site.title || Constants::DEFAULT_SITE_TITLE,
-        site_description: config.site.description || "",
-        favicon: config.branding.favicon
+        site_title: config.title || Constants::DEFAULT_SITE_TITLE,
+        site_description: config.description || "",
+        favicon: config.branding.favicon || auto_detect_favicon
       }
     end
 
     def logo_options
       branding = config.branding
+      logo = branding.logo || auto_detect_logo
+      has_custom_logo = !logo.nil?
       {
-        logo: resolve_logo(branding.logo, branding.logo_dark),
-        logo_dark: resolve_logo_dark(branding.logo, branding.logo_dark)
+        logo: logo || Constants::DEFAULT_LOGO_PATH,
+        logo_dark: detect_dark_logo(logo) || Constants::DEFAULT_LOGO_DARK_PATH,
+        has_custom_logo: has_custom_logo
       }
     end
 
+    def auto_detect_logo
+      detect_public_file("logo", %w[svg png])
+    end
+
+    def auto_detect_favicon
+      detect_public_file("favicon", %w[ico svg png])
+    end
+
+    def detect_public_file(name, extensions)
+      extensions.each do |ext|
+        path = File.join(Constants::PUBLIC_DIR, "#{name}.#{ext}")
+        return "#{name}.#{ext}" if File.exist?(path)
+      end
+      nil
+    end
+
+    def detect_dark_logo(logo)
+      return nil unless logo
+
+      ext = File.extname(logo)
+      base = File.basename(logo, ext)
+      dark_filename = "#{base}-dark#{ext}"
+
+      if File.absolute_path?(logo)
+        dark_path = File.join(File.dirname(logo), dark_filename)
+        File.exist?(dark_path) ? dark_path : logo
+      else
+        dark_path = File.join("docs/public", dark_filename)
+        File.exist?(dark_path) ? dark_filename : logo
+      end
+    end
+
     def search_options
       {
         search_enabled: config.search.enabled != false,
-        search_placeholder: config.search.placeholder || "Search documentation..."
+        search_placeholder: config.search.placeholder || "Search..."
       }
     end
 
-    def appearance_options
-      appearance = config.branding.appearance || {}
+    def credits_options
       {
-        display_logo: appearance["logo"] != false,
-        display_title: appearance["title"] != false
+        credits: config.branding.credits != false,
+        copyright: config.branding.copyright
       }
     end
 
-    def resolve_logo(logo, logo_dark)
-      logo || logo_dark || Constants::DEFAULT_LOGO_PATH
+    def social_options
+      socials = config.socials || {}
+      {
+        social: normalize_social_links(socials)
+      }
     end
 
-    def resolve_logo_dark(logo, logo_dark)
-      logo_dark || logo || Constants::DEFAULT_LOGO_DARK_PATH
+    def normalize_social_links(socials)
+      return [] unless socials.is_a?(Hash) && socials.any?
+
+      socials.filter_map { |platform, url| build_social_link(platform.to_s, url) }
+    end
+
+    def build_social_link(platform, url)
+      return if platform == "custom" || !valid_url?(url)
+
+      { platform: platform, url: url, icon: SOCIAL_ICON_MAP[platform] || platform }
+    end
+
+    def valid_url?(url)
+      url.is_a?(String) && !url.strip.empty?
+    end
+
+    def navigation_options
+      cta_items = config.navigation.cta || []
+      {
+        header_ctas: normalize_cta_items(cta_items)
+      }
+    end
+
+    def normalize_cta_items(items)
+      return [] unless items.is_a?(Array)
+
+      items.first(2).filter_map do |item|
+        next unless item.is_a?(Hash) && item["text"] && item["href"]
+
+        {
+          text: item["text"],
+          href: item["href"],
+          variant: item["variant"] || "primary",
+          external: item["external"] == true
+        }
+      end
+    end
+
+    def tabs_options
+      tab_items = config.tabs || []
+      {
+        tabs: normalize_tab_items(tab_items),
+        has_tabs: tab_items.any?
+      }
+    end
+
+    def normalize_tab_items(items)
+      return [] unless items.is_a?(Array)
+
+      items.filter_map do |item|
+        next unless item.is_a?(Hash) && item["text"] && item["href"]
+
+        {
+          text: item["text"],
+          href: item["href"],
+          icon: item["icon"],
+          external: item["external"] == true
+        }
+      end
     end
   end
 end