docyard 0.6.0 → 0.7.0

data/lib/docyard/{sidebar → navigation/sidebar}/renderer.rb

@@ -5,7 +5,9 @@ require "erb"
 module Docyard
   module Sidebar
     class Renderer
-      PARTIALS_PATH = File.join(__dir__, "../templates/partials")
+      include Utils::UrlHelpers
+
+      PARTIALS_PATH = File.join(__dir__, "../../templates/partials")
 
       attr_reader :site_title, :base_url
 
@@ -39,19 +41,6 @@ module Docyard
         Icons.render(name.to_s.tr("_", "-"), weight) || ""
       end
 
-      def link_path(path)
-        return path if path.nil? || path.start_with?("http://", "https://")
-
-        "#{base_url.chomp('/')}#{path}"
-      end
-
-      def normalize_base_url(url)
-        return "/" if url.nil? || url.empty?
-
-        url = "/#{url}" unless url.start_with?("/")
-        url.end_with?("/") ? url : "#{url}/"
-      end
-
       def render_tree_with_sections(items)
         filtered_items = items.reject { |item| item[:title]&.downcase == site_title.downcase }
         grouped_items = group_by_section(filtered_items)

data/lib/docyard/{sidebar → navigation/sidebar}/tree_builder.rb

@@ -29,6 +29,7 @@ module Docyard
 
       def transform_directory(item, relative_base)
         dir_path = File.join(relative_base, item[:name])
+        children = transform_items(item[:children], dir_path)
 
         {
           title: Utils::TextFormatter.titleize(item[:name]),
@@ -36,11 +37,17 @@ module Docyard
           active: false,
           type: :directory,
           collapsible: true,
-          collapsed: false,
-          children: transform_items(item[:children], dir_path)
+          collapsed: !active_child?(children),
+          children: children
         }
       end
 
+      def active_child?(children)
+        children.any? do |child|
+          child[:active] || active_child?(child[:children] || [])
+        end
+      end
+
       def transform_file(item, relative_base)
         file_path = File.join(relative_base, "#{item[:name]}#{Constants::MARKDOWN_EXTENSION}")
         full_file_path = File.join(docs_path, file_path)

data/lib/docyard/{sidebar_builder.rb → navigation/sidebar_builder.rb}

@@ -50,11 +50,7 @@ module Docyard
     def config_sidebar_items
       return [] unless config
 
-      if config.is_a?(Hash)
-        config.dig("sidebar", "items") || config.dig(:sidebar, :items) || []
-      else
-        config.sidebar&.items || []
-      end
+      config.sidebar&.items || []
     end
 
     def config_parser
@@ -84,19 +80,11 @@ module Docyard
     end
 
     def extract_base_url
-      if config.is_a?(Hash)
-        config.dig(:build, :base_url) || "/"
-      else
-        config&.build&.base_url || "/"
-      end
+      config&.build&.base_url || "/"
     end
 
     def extract_site_title
-      if config.is_a?(Hash)
-        config[:site_title] || "Documentation"
-      else
-        config&.site&.title || "Documentation"
-      end
+      config&.site&.title || "Documentation"
     end
   end
 end

data/lib/docyard/{icons → rendering/icons}/phosphor.rb

@@ -36,7 +36,10 @@ module Docyard
         "siren" => '<path d="M120,16V8a8,8,0,0,1,16,0v8a8,8,0,0,1-16,0Zm80,32a8,8,0,0,0,5.66-2.34l8-8a8,8,0,0,0-11.32-11.32l-8,8A8,8,0,0,0,200,48ZM50.34,45.66A8,8,0,0,0,61.66,34.34l-8-8A8,8,0,0,0,42.34,37.66Zm87,26.45a8,8,0,1,0-2.64,15.78C153.67,91.08,168,108.32,168,128a8,8,0,0,0,16,0C184,100.6,163.93,76.57,137.32,72.11ZM232,176v24a16,16,0,0,1-16,16H40a16,16,0,0,1-16-16V176a16,16,0,0,1,16-16V128a88,88,0,0,1,88.67-88c48.15.36,87.33,40.29,87.33,89v31A16,16,0,0,1,232,176ZM56,160H200V129c0-40-32.05-72.71-71.45-73H128a72,72,0,0,0-72,72Zm160,40V176H40v24H216Z"/>',
         "file" => '<path d="M213.66,82.34l-56-56A8,8,0,0,0,152,24H56A16,16,0,0,0,40,40V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V88A8,8,0,0,0,213.66,82.34ZM160,51.31,188.69,80H160ZM200,216H56V40h88V88a8,8,0,0,0,8,8h48V216Z"/>',
         "terminal-window" => '<path d="M128,128a8,8,0,0,1-3,6.25l-40,32a8,8,0,1,1-10-12.5L107.19,128,75,102.25a8,8,0,1,1,10-12.5l40,32A8,8,0,0,1,128,128Zm48,24H136a8,8,0,0,0,0,16h40a8,8,0,0,0,0-16Zm56-96V200a16,16,0,0,1-16,16H40a16,16,0,0,1-16-16V56A16,16,0,0,1,40,40H216A16,16,0,0,1,232,56ZM216,200V56H40V200H216Z"/>',
-        "list-dashes" => '<path d="M88,64a8,8,0,0,1,8-8H216a8,8,0,0,1,0,16H96A8,8,0,0,1,88,64Zm128,56H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Zm0,64H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16ZM56,56H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Z"/>'
+        "list-dashes" => '<path d="M88,64a8,8,0,0,1,8-8H216a8,8,0,0,1,0,16H96A8,8,0,0,1,88,64Zm128,56H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Zm0,64H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16ZM56,56H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Z"/>',
+        "magnifying-glass" => '<path d="M229.66,218.34l-50.07-50.06a88.11,88.11,0,1,0-11.31,11.31l50.06,50.07a8,8,0,0,0,11.32-11.32ZM40,112a72,72,0,1,1,72,72A72.08,72.08,0,0,1,40,112Z"/>',
+        "command" => '<path d="M180,144H160V112h20a36,36,0,1,0-36-36V96H112V76a36,36,0,1,0-36,36H96v32H76a36,36,0,1,0,36,36V160h32v20a36,36,0,1,0,36-36ZM160,76a20,20,0,1,1,20,20H160ZM56,76a20,20,0,0,1,40,0V96H76A20,20,0,0,1,56,76ZM96,180a20,20,0,1,1-20-20H96Zm16-68h32v32H112Zm68,88a20,20,0,0,1-20-20V160h20a20,20,0,0,1,0,40Z"/>',
+        "hash" => '<path d="M224,88H175.4l8.47-46.57a8,8,0,0,0-15.74-2.86l-9,49.43H111.4l8.47-46.57a8,8,0,0,0-15.74-2.86L95.14,88H48a8,8,0,0,0,0,16H92.23L83.5,152H32a8,8,0,0,0,0,16H80.6l-8.47,46.57a8,8,0,0,0,6.44,9.3A7.79,7.79,0,0,0,80,224a8,8,0,0,0,7.86-6.57l9-49.43H144.6l-8.47,46.57a8,8,0,0,0,6.44,9.3,7.79,7.79,0,0,0,1.43.13,8,8,0,0,0,7.86-6.57l9-49.43H208a8,8,0,0,0,0-16H163.77l8.73-48H224a8,8,0,0,0,0-16Zm-68.5,64H107.77l8.73-48h47.73Z"/>'
       },
       "bold" => {
         "heart" => '<path d="M178,36c-20.09,0-37.92,7.93-50,21.56C115.92,43.93,98.09,36,78,36a66.08,66.08,0,0,0-66,66c0,72.34,105.81,130.14,110.31,132.57a12,12,0,0,0,11.38,0C138.19,232.14,244,174.34,244,102A66.08,66.08,0,0,0,178,36Zm-5.49,142.36A328.69,328.69,0,0,1,128,210.16a328.69,328.69,0,0,1-44.51-31.8C61.82,159.77,36,131.42,36,102A42,42,0,0,1,78,60c17.8,0,32.7,9.4,38.89,24.54a12,12,0,0,0,22.22,0C145.3,69.4,160.2,60,178,60a42,42,0,0,1,42,42C220,131.42,194.18,159.77,172.51,178.36Z"/>'

data/lib/docyard/{markdown.rb → rendering/markdown.rb}

@@ -3,19 +3,20 @@
 require "kramdown"
 require "kramdown-parser-gfm"
 require "yaml"
-require_relative "components/registry"
-require_relative "components/base_processor"
-require_relative "components/callout_processor"
-require_relative "components/tabs_processor"
-require_relative "components/icon_processor"
-require_relative "components/code_block_processor"
-require_relative "components/code_snippet_import_preprocessor"
-require_relative "components/code_block_options_preprocessor"
-require_relative "components/code_block_diff_preprocessor"
-require_relative "components/code_block_focus_preprocessor"
-require_relative "components/table_wrapper_processor"
-require_relative "components/heading_anchor_processor"
-require_relative "components/table_of_contents_processor"
+require_relative "../components/registry"
+require_relative "../components/base_processor"
+require_relative "../components/processors/callout_processor"
+require_relative "../components/processors/tabs_processor"
+require_relative "../components/processors/icon_processor"
+require_relative "../components/processors/code_block_processor"
+require_relative "../components/processors/code_snippet_import_preprocessor"
+require_relative "../components/processors/code_block_options_preprocessor"
+require_relative "../components/processors/code_block_diff_preprocessor"
+require_relative "../components/processors/code_block_focus_preprocessor"
+require_relative "../components/processors/table_wrapper_processor"
+require_relative "../components/processors/heading_anchor_processor"
+require_relative "../components/processors/table_of_contents_processor"
+require_relative "../components/aliases"
 
 module Docyard
   class Markdown

data/lib/docyard/{renderer.rb → rendering/renderer.rb}

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
 require "erb"
-require_relative "constants"
+require_relative "../config/constants"
 
 module Docyard
   class Renderer
-    LAYOUTS_PATH = File.join(__dir__, "templates", "layouts")
-    ERRORS_PATH = File.join(__dir__, "templates", "errors")
-    PARTIALS_PATH = File.join(__dir__, "templates", "partials")
+    include Utils::UrlHelpers
+
+    LAYOUTS_PATH = File.join(__dir__, "../templates", "layouts")
+    ERRORS_PATH = File.join(__dir__, "../templates", "errors")
+    PARTIALS_PATH = File.join(__dir__, "../templates", "partials")
 
     attr_reader :layout_path, :base_url, :config
 
@@ -80,21 +82,8 @@ module Docyard
       "#{base_url}#{path}"
     end
 
-    def link_path(path)
-      return path if path.nil? || path.start_with?("http://", "https://")
-
-      "#{base_url.chomp('/')}#{path}"
-    end
-
     private
 
-    def normalize_base_url(url)
-      return "/" if url.nil? || url.empty?
-
-      url = "/#{url}" unless url.start_with?("/")
-      url.end_with?("/") ? url : "#{url}/"
-    end
-
     def assign_content_variables(content, page_title, sidebar_html, prev_next_html, toc)
       @content = content
       @page_title = page_title
@@ -104,15 +93,29 @@ module Docyard
     end
 
     def assign_branding_variables(branding)
+      assign_site_branding(branding)
+      assign_display_options(branding)
+      assign_search_options(branding)
+    end
+
+    def assign_site_branding(branding)
       @site_title = branding[:site_title] || Constants::DEFAULT_SITE_TITLE
       @site_description = branding[:site_description] || ""
       @logo = branding[:logo] || Constants::DEFAULT_LOGO_PATH
       @logo_dark = branding[:logo_dark]
       @favicon = branding[:favicon] || Constants::DEFAULT_FAVICON_PATH
+    end
+
+    def assign_display_options(branding)
       @display_logo = branding[:display_logo].nil? || branding[:display_logo]
       @display_title = branding[:display_title].nil? || branding[:display_title]
     end
 
+    def assign_search_options(branding)
+      @search_enabled = branding[:search_enabled].nil? || branding[:search_enabled]
+      @search_placeholder = branding[:search_placeholder] || "Search documentation..."
+    end
+
     def strip_md_from_links(html)
       html.gsub(/href="([^"]+)\.md"/, 'href="\1"')
     end

data/lib/docyard/search/build_indexer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Docyard
+  module Search
+    class BuildIndexer
+      include PagefindSupport
+
+      PAGEFIND_COMMAND = "npx"
+
+      attr_reader :config, :output_dir, :verbose
+
+      def initialize(config, verbose: false)
+        @config = config
+        @output_dir = config.build.output_dir
+        @verbose = verbose
+      end
+
+      def index
+        return 0 unless search_enabled?
+
+        log "Generating search index..."
+
+        unless pagefind_available?
+          warn_pagefind_missing
+          return 0
+        end
+
+        run_pagefind
+      end
+
+      private
+
+      def warn_pagefind_missing
+        log_warning "[!] Search index skipped: Pagefind not found"
+        log_warning "    Install with: npm install -g pagefind"
+        log_warning "    Or run: npx pagefind --site #{output_dir}"
+      end
+
+      def run_pagefind
+        args = build_pagefind_args(output_dir)
+        log "Running: npx #{args.join(' ')}" if verbose
+
+        stdout, stderr, status = Open3.capture3(PAGEFIND_COMMAND, *args)
+
+        if status.success?
+          page_count = extract_page_count(stdout)
+          log "[+] Generated search index (#{page_count} pages indexed)"
+          page_count
+        else
+          log_warning "[!] Search indexing failed: #{stderr}"
+          0
+        end
+      end
+
+      def extract_page_count(output)
+        if output =~ /Indexed (\d+) page/i
+          Regexp.last_match(1).to_i
+        else
+          0
+        end
+      end
+
+      def log(message)
+        puts message
+      end
+
+      def log_warning(message)
+        warn message
+      end
+    end
+  end
+end

data/lib/docyard/search/dev_indexer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+require "open3"
+require "tty-progressbar"
+
+module Docyard
+  module Search
+    class DevIndexer
+      include PagefindSupport
+
+      attr_reader :docs_path, :config, :temp_dir, :pagefind_path
+
+      def initialize(docs_path:, config:)
+        @docs_path = docs_path
+        @config = config
+        @temp_dir = nil
+        @pagefind_path = nil
+      end
+
+      def generate
+        return unless search_enabled?
+        return unless pagefind_available?
+
+        @temp_dir = Dir.mktmpdir("docyard-search-")
+        generate_html_files
+        run_pagefind
+        @pagefind_path = File.join(temp_dir, "pagefind")
+
+        log_success
+        pagefind_path
+      rescue StandardError => e
+        warn "[!] Search index generation failed: #{e.message}"
+        cleanup
+        nil
+      end
+
+      def cleanup
+        return unless temp_dir && Dir.exist?(temp_dir)
+
+        FileUtils.rm_rf(temp_dir)
+      end
+
+      private
+
+      def pagefind_available?
+        result = super
+        warn "[!] Search disabled: Pagefind not found (npm install -g pagefind)" unless result
+        result
+      end
+
+      def generate_html_files
+        markdown_files = Dir.glob(File.join(docs_path, "**", "*.md"))
+        renderer = Renderer.new(base_url: "/", config: config)
+
+        progress = TTY::ProgressBar.new(
+          "Indexing search [:bar] :current/:total (:percent)",
+          total: markdown_files.size,
+          width: 50
+        )
+
+        markdown_files.each do |file_path|
+          generate_html_file(file_path, renderer)
+          progress.advance
+        end
+      end
+
+      def generate_html_file(markdown_file, renderer)
+        relative_path = markdown_file.delete_prefix("#{docs_path}/")
+        output_path = determine_output_path(relative_path)
+
+        html = renderer.render_file(markdown_file, branding: branding_options)
+
+        FileUtils.mkdir_p(File.dirname(output_path))
+        File.write(output_path, html)
+      end
+
+      def determine_output_path(relative_path)
+        base_name = File.basename(relative_path, ".md")
+        dir_name = File.dirname(relative_path)
+
+        if base_name == "index"
+          File.join(temp_dir, dir_name, "index.html")
+        else
+          File.join(temp_dir, dir_name, base_name, "index.html")
+        end
+      end
+
+      def branding_options
+        BrandingResolver.new(config).resolve
+      end
+
+      def run_pagefind
+        args = build_pagefind_args(temp_dir)
+        stdout, stderr, status = Open3.capture3("npx", *args)
+
+        raise "Pagefind failed: #{stderr}" unless status.success?
+
+        stdout
+      end
+
+      def log_success
+        page_count = Dir.glob(File.join(temp_dir, "**", "*.html")).size
+        puts "=> Search index generated (#{page_count} pages)"
+        puts "=> Temp directory: #{temp_dir}" if ENV["DOCYARD_DEBUG"]
+      end
+    end
+  end
+end

data/lib/docyard/search/pagefind_support.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Docyard
+  module Search
+    module PagefindSupport
+      def search_enabled?
+        config.search.enabled != false
+      end
+
+      def pagefind_available?
+        _stdout, _stderr, status = Open3.capture3("npx", "pagefind", "--version")
+        status.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      def build_pagefind_args(site_dir)
+        args = ["pagefind", "--site", site_dir]
+
+        exclusions = config.search.exclude || []
+        exclusions.each do |pattern|
+          args += ["--exclude-selectors", pattern]
+        end
+
+        args
+      end
+    end
+  end
+end

data/lib/docyard/{asset_handler.rb → server/asset_handler.rb}

@@ -2,7 +2,7 @@
 
 module Docyard
   class AssetHandler
-    ASSETS_PATH = File.join(__dir__, "templates", "assets")
+    ASSETS_PATH = File.join(__dir__, "../templates", "assets")
     USER_ASSETS_PATH = "docs/assets"
 
     CONTENT_TYPES = {

data/lib/docyard/{server.rb → server/dev_server.rb}

@@ -4,30 +4,30 @@ require "webrick"
 require "stringio"
 require_relative "file_watcher"
 require_relative "rack_application"
-require_relative "config"
+require_relative "../config"
 
 module Docyard
   class Server
     DEFAULT_PORT = 4200
     DEFAULT_HOST = "localhost"
 
-    attr_reader :port, :host, :docs_path, :config
+    attr_reader :port, :host, :docs_path, :config, :search_enabled
 
-    def initialize(port: DEFAULT_PORT, host: DEFAULT_HOST, docs_path: "docs")
+    def initialize(port: DEFAULT_PORT, host: DEFAULT_HOST, docs_path: "docs", search: false)
       @port = port
       @host = host
       @docs_path = docs_path
+      @search_enabled = search
       @config = Config.load
       @file_watcher = FileWatcher.new(File.expand_path(docs_path))
-      @app = RackApplication.new(
-        docs_path: File.expand_path(docs_path),
-        file_watcher: @file_watcher,
-        config: @config
-      )
+      @search_indexer = nil
+      @app = nil
     end
 
     def start
       validate_docs_directory!
+      generate_search_index if @search_enabled
+      initialize_app
       print_server_info
       @file_watcher.start
 
@@ -35,11 +35,33 @@ module Docyard
       trap("INT") { shutdown_server }
 
       http_server.start
-      @file_watcher.stop
+      cleanup
     end
 
     private
 
+    def generate_search_index
+      @search_indexer = Search::DevIndexer.new(
+        docs_path: File.expand_path(docs_path),
+        config: @config
+      )
+      @search_indexer.generate
+    end
+
+    def initialize_app
+      @app = RackApplication.new(
+        docs_path: File.expand_path(docs_path),
+        file_watcher: @file_watcher,
+        config: @config,
+        pagefind_path: @search_indexer&.pagefind_path
+      )
+    end
+
+    def cleanup
+      @file_watcher.stop
+      @search_indexer&.cleanup
+    end
+
     def validate_docs_directory!
       return if File.directory?(docs_path)
 
@@ -51,6 +73,7 @@ module Docyard
       puts "Starting Docyard server..."
       puts "=> Serving docs from: #{docs_path}/"
       puts "=> Running at: http://#{host}:#{port}"
+      puts "=> Search: #{@search_enabled ? 'enabled' : 'disabled (use --search to enable)'}"
       puts "=> Press Ctrl+C to stop\n"
     end
 

data/lib/docyard/{preview_server.rb → server/preview_server.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "webrick"
-require_relative "config"
+require_relative "../config"
 
 module Docyard
   class PreviewServer

data/lib/docyard/{rack_application.rb → server/rack_application.rb}

@@ -2,16 +2,24 @@
 
 require "json"
 require "rack"
-require_relative "sidebar_builder"
-require_relative "prev_next_builder"
-require_relative "constants"
+require_relative "../navigation/sidebar_builder"
+require_relative "../navigation/prev_next_builder"
+require_relative "../config/branding_resolver"
+require_relative "../config/constants"
 
 module Docyard
   class RackApplication
-    def initialize(docs_path:, file_watcher:, config: nil)
+    PAGEFIND_CONTENT_TYPES = {
+      ".js" => "application/javascript; charset=utf-8",
+      ".css" => "text/css; charset=utf-8",
+      ".json" => "application/json; charset=utf-8"
+    }.freeze
+
+    def initialize(docs_path:, file_watcher:, config: nil, pagefind_path: nil)
       @docs_path = docs_path
       @file_watcher = file_watcher
       @config = config
+      @pagefind_path = pagefind_path
       @router = Router.new(docs_path: docs_path)
       @renderer = Renderer.new(base_url: config&.build&.base_url || "/", config: config)
       @asset_handler = AssetHandler.new
@@ -23,13 +31,14 @@ module Docyard
 
     private
 
-    attr_reader :docs_path, :file_watcher, :config, :router, :renderer, :asset_handler
+    attr_reader :docs_path, :file_watcher, :config, :pagefind_path, :router, :renderer, :asset_handler
 
     def handle_request(env)
       path = env["PATH_INFO"]
 
       return handle_reload_check(env) if path == Constants::RELOAD_ENDPOINT
       return asset_handler.serve(path) if path.start_with?(Constants::ASSETS_PREFIX)
+      return serve_pagefind(path) if path.start_with?(Constants::PAGEFIND_PREFIX)
 
       handle_documentation_request(path)
     rescue StandardError => e
@@ -91,50 +100,7 @@ module Docyard
     end
 
     def branding_options
-      return default_branding unless config
-
-      default_branding.merge(config_branding_options)
-    end
-
-    def default_branding
-      {
-        site_title: Constants::DEFAULT_SITE_TITLE,
-        site_description: "",
-        logo: Constants::DEFAULT_LOGO_PATH,
-        logo_dark: Constants::DEFAULT_LOGO_DARK_PATH,
-        favicon: nil,
-        display_logo: true,
-        display_title: true
-      }
-    end
-
-    def config_branding_options
-      site = config.site
-      branding = config.branding
-
-      {
-        site_title: site.title || Constants::DEFAULT_SITE_TITLE,
-        site_description: site.description || "",
-        logo: resolve_logo(branding.logo, branding.logo_dark),
-        logo_dark: resolve_logo_dark(branding.logo, branding.logo_dark),
-        favicon: branding.favicon
-      }.merge(appearance_options(branding.appearance))
-    end
-
-    def appearance_options(appearance)
-      appearance ||= {}
-      {
-        display_logo: appearance["logo"] != false,
-        display_title: appearance["title"] != false
-      }
-    end
-
-    def resolve_logo(logo, logo_dark)
-      logo || logo_dark || Constants::DEFAULT_LOGO_PATH
-    end
-
-    def resolve_logo_dark(logo, logo_dark)
-      logo_dark || logo || Constants::DEFAULT_LOGO_DARK_PATH
+      BrandingResolver.new(config).resolve
     end
 
     def handle_reload_check(env)
@@ -168,5 +134,42 @@ module Docyard
       [Constants::STATUS_INTERNAL_ERROR, { "Content-Type" => Constants::CONTENT_TYPE_HTML },
        [renderer.render_server_error(error)]]
     end
+
+    def serve_pagefind(path)
+      relative_path = path.delete_prefix(Constants::PAGEFIND_PREFIX)
+      return pagefind_not_found if relative_path.include?("..")
+
+      file_path = resolve_pagefind_file(relative_path)
+      return pagefind_not_found unless file_path && File.file?(file_path)
+
+      content = File.binread(file_path)
+      content_type = pagefind_content_type(file_path)
+
+      headers = {
+        "Content-Type" => content_type,
+        "Cache-Control" => "no-cache, no-store, must-revalidate",
+        "Pragma" => "no-cache",
+        "Expires" => "0"
+      }
+
+      [Constants::STATUS_OK, headers, [content]]
+    end
+
+    def resolve_pagefind_file(relative_path)
+      return File.join(pagefind_path, relative_path) if pagefind_path && Dir.exist?(pagefind_path)
+
+      output_dir = config&.build&.output_dir || "dist"
+      File.join(output_dir, "pagefind", relative_path)
+    end
+
+    def pagefind_content_type(file_path)
+      extension = File.extname(file_path)
+      PAGEFIND_CONTENT_TYPES.fetch(extension, "application/octet-stream")
+    end
+
+    def pagefind_not_found
+      message = "Pagefind not found. Run 'docyard build' first."
+      [Constants::STATUS_NOT_FOUND, { "Content-Type" => "text/plain" }, [message]]
+    end
   end
 end