docyard 1.0.1 → 1.1.0

data/lib/docyard/search/build_indexer.rb

@@ -18,39 +18,26 @@ module Docyard
       end
 
       def index
-        return 0 unless search_enabled?
-
-        log "Generating search index..."
-
-        unless pagefind_available?
-          warn_pagefind_missing
-          return 0
-        end
+        return [0, nil] unless search_enabled?
+        return [0, nil] unless pagefind_available?
 
         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
+          count = extract_page_count(stdout)
+          details = verbose ? collect_index_details : nil
+          [count, details]
         else
-          log_warning "[!] Search indexing failed: #{stderr}"
-          0
+          Docyard.logger.warn("Search indexing failed: #{stderr}") if verbose
+          [0, nil]
         end
       end
 
@@ -62,12 +49,40 @@ module Docyard
         end
       end
 
-      def log(message)
-        Docyard.logger.info(message)
+      def collect_index_details
+        indexed, excluded = classify_pages
+        format_index_details(indexed, excluded)
+      end
+
+      def classify_pages
+        indexed = []
+        excluded = []
+
+        Dir.glob(File.join(output_dir, "**", "index.html")).each do |file|
+          path = extract_page_path(file)
+          classify_page(File.read(file), path, indexed, excluded)
+        end
+
+        [indexed, excluded]
+      end
+
+      def extract_page_path(file)
+        path = file.delete_prefix("#{output_dir}/").delete_suffix("/index.html")
+        path.empty? ? "/" : path
+      end
+
+      def classify_page(content, path, indexed, excluded)
+        if content.include?("data-pagefind-body")
+          indexed << path
+        elsif content.include?("data-pagefind-ignore")
+          excluded << path
+        end
       end
 
-      def log_warning(message)
-        Docyard.logger.warn(message)
+      def format_index_details(indexed, excluded)
+        details = indexed.sort
+        excluded.sort.each { |path| details << "(excluded: #{path})" } if excluded.any?
+        details
       end
     end
   end

data/lib/docyard/search/dev_indexer.rb

@@ -4,7 +4,6 @@ require "fileutils"
 require "tmpdir"
 require "open3"
 require "parallel"
-require "tty-progressbar"
 require_relative "../utils/path_utils"
 
 module Docyard
@@ -14,13 +13,15 @@ module Docyard
 
       PARALLEL_THRESHOLD = 10
 
-      attr_reader :docs_path, :config, :temp_dir, :pagefind_path
+      attr_reader :docs_path, :config, :temp_dir, :pagefind_path, :page_count, :total_pages
 
       def initialize(docs_path:, config:)
         @docs_path = docs_path
         @config = config
         @temp_dir = nil
         @pagefind_path = nil
+        @page_count = 0
+        @total_pages = 0
       end
 
       def generate
@@ -29,10 +30,9 @@ module Docyard
 
         @temp_dir = Dir.mktmpdir("docyard-search-")
         generate_html_files
-        page_count = run_pagefind
+        @page_count = run_pagefind
         @pagefind_path = File.join(temp_dir, "_docyard", "pagefind")
 
-        log_success(page_count)
         pagefind_path
       rescue StandardError => e
         Docyard.logger.warn("Search index generation failed: #{e.message}")
@@ -58,36 +58,27 @@ module Docyard
         markdown_files = Dir.glob(File.join(docs_path, "**", "*.md"))
         markdown_files = filter_excluded_files(markdown_files)
         markdown_files = filter_non_indexable_files(markdown_files)
-
-        progress = TTY::ProgressBar.new(
-          "Indexing search [:bar] :current/:total (:percent)",
-          total: markdown_files.size,
-          width: 50
-        )
-        mutex = Mutex.new
+        @total_pages = markdown_files.size
 
         Logging.start_buffering
         if markdown_files.size >= PARALLEL_THRESHOLD
-          generate_files_in_parallel(markdown_files, progress, mutex)
+          generate_files_in_parallel(markdown_files)
         else
-          generate_files_sequentially(markdown_files, progress)
+          generate_files_sequentially(markdown_files)
         end
-        Logging.flush_warnings
       end
 
-      def generate_files_in_parallel(markdown_files, progress, mutex)
+      def generate_files_in_parallel(markdown_files)
         Parallel.each(markdown_files, in_threads: Parallel.processor_count) do |file_path|
           renderer = thread_local_renderer
           generate_html_file(file_path, renderer)
-          mutex.synchronize { progress.advance }
         end
       end
 
-      def generate_files_sequentially(markdown_files, progress)
+      def generate_files_sequentially(markdown_files)
         renderer = Renderer.new(base_url: "/", config: config)
         markdown_files.each do |file_path|
           generate_html_file(file_path, renderer)
-          progress.advance
         end
       end
 
@@ -153,11 +144,6 @@ module Docyard
         match = output.match(/Indexed (\d+) page/i)
         match ? match[1].to_i : 0
       end
-
-      def log_success(page_count)
-        Docyard.logger.info("* Search index generated (#{page_count} pages indexed)")
-        Docyard.logger.debug("* Temp directory: #{temp_dir}")
-      end
     end
   end
 end

data/lib/docyard/server/dev_server.rb

@@ -9,13 +9,15 @@ require_relative "sse_server"
 require_relative "file_watcher"
 require_relative "../config"
 require_relative "../navigation/sidebar/cache"
+require_relative "../doctor/config_checker"
+require_relative "../doctor/sidebar_checker"
 
 module Docyard
   class DevServer
     DEFAULT_PORT = 4200
     DEFAULT_HOST = "localhost"
 
-    attr_reader :port, :host, :docs_path, :config, :search_enabled
+    attr_reader :port, :host, :docs_path, :config, :search_enabled, :global_diagnostics
 
     def initialize(port: DEFAULT_PORT, host: DEFAULT_HOST, docs_path: "docs", search: false)
       @port = port
@@ -28,12 +30,13 @@ module Docyard
       @file_watcher = nil
       @launcher = nil
       @sidebar_cache = nil
+      @global_diagnostics = []
     end
 
     def start
       validate_docs_directory!
       build_sidebar_cache
-      generate_search_index if @search_enabled
+      collect_global_diagnostics
       setup_hot_reload
       print_server_info
       run_server
@@ -51,6 +54,14 @@ module Docyard
       @sidebar_cache.build
     end
 
+    def collect_global_diagnostics
+      @global_diagnostics.clear
+      @global_diagnostics.concat(Doctor::ConfigChecker.new(@config).check)
+      @global_diagnostics.concat(Doctor::SidebarChecker.new(File.expand_path(docs_path)).check)
+    rescue StandardError => e
+      Docyard.logger.warn("Diagnostic collection failed: #{e.message}")
+    end
+
     def generate_search_index
       @search_indexer = Search::DevIndexer.new(
         docs_path: File.expand_path(docs_path),
@@ -75,11 +86,22 @@ module Docyard
     end
 
     def handle_file_change(change_type)
-      invalidate_sidebar_cache if change_type == :full
+      if change_type == :full
+        reload_config
+        invalidate_sidebar_cache
+        collect_global_diagnostics
+        @sse_server.broadcast("diagnostics", { global: @global_diagnostics.map(&:to_h) })
+      end
       log_file_change(change_type)
       @sse_server.broadcast("reload", { type: change_type.to_s })
     end
 
+    def reload_config
+      @config = Config.load
+    rescue ConfigError => e
+      Docyard.logger.warn("Config reload failed: #{e.message}")
+    end
+
     def invalidate_sidebar_cache
       @sidebar_cache&.invalidate
       @sidebar_cache&.build
@@ -88,7 +110,7 @@ module Docyard
     def log_file_change(change_type)
       message = case change_type
                 when :content then "Content changed, reloading..."
-                when :config then "Config changed, full reload..."
+                when :full then "Config changed, full reload..."
                 when :asset then "Asset changed, reloading..."
                 else "File changed, reloading..."
                 end
@@ -104,17 +126,36 @@ module Docyard
     def validate_docs_directory!
       return if File.directory?(docs_path)
 
-      abort "Error: #{docs_path}/ directory not found.\n" \
+      abort "#{UI.error('Error:')} #{docs_path}/ directory not found.\n" \
             "Run `docyard init` first to create the docs structure."
     end
 
-    def print_server_info
-      Docyard.logger.info("Starting Docyard server...")
-      Docyard.logger.info("* Version: #{Docyard::VERSION}")
-      Docyard.logger.info("* Running at: http://#{host}:#{port}")
-      Docyard.logger.info("* Hot reload: ws://127.0.0.1:#{sse_port}")
-      Docyard.logger.info("* Search: #{@search_enabled ? 'enabled' : 'disabled (use --search to enable)'}")
-      Docyard.logger.info("Use Ctrl+C to stop\n")
+    def print_server_info # rubocop:disable Metrics/AbcSize
+      search_status = @search_enabled ? UI.green("enabled") : UI.dim("disabled")
+
+      puts
+      puts "  #{UI.bold('Docyard')} v#{Docyard::VERSION}"
+      puts
+      puts "  Serving #{docs_path}/"
+      puts "  #{UI.cyan("http://#{host}:#{port}")}"
+      puts
+      puts "  Hot reload: #{UI.cyan("ws://#{host}:#{sse_port}")}"
+      puts "  Search:     #{search_status}"
+      print_indexing_status if @search_enabled
+      puts
+      puts "  #{UI.dim('Press Ctrl+C to stop')}"
+      puts
+    end
+
+    def print_indexing_status
+      print "  Indexing:   #{UI.dim('in progress')}"
+      $stdout.flush
+      generate_search_index
+      count = @search_indexer&.page_count || 0
+      total = @search_indexer&.total_pages || 0
+      print "\r  Indexing:   #{UI.green("done (#{count}/#{total} pages)")}\n"
+      $stdout.flush
+      Logging.flush_warnings
     end
 
     def run_server
@@ -132,7 +173,8 @@ module Docyard
         config: @config,
         pagefind_path: @search_indexer&.pagefind_path,
         sse_port: sse_port,
-        sidebar_cache: @sidebar_cache
+        sidebar_cache: @sidebar_cache,
+        global_diagnostics: @global_diagnostics
       )
     end
 

data/lib/docyard/server/error_overlay.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../editor_launcher"
+
+module Docyard
+  class ErrorOverlay
+    CATEGORY_LABELS = {
+      CONFIG: "Configuration",
+      SIDEBAR: "Sidebar",
+      CONTENT: "Content",
+      COMPONENT: "Component",
+      LINK: "Links",
+      IMAGE: "Images",
+      SYNTAX: "Syntax",
+      ORPHAN: "Orphan Pages"
+    }.freeze
+
+    GLOBAL_CATEGORIES = %i[CONFIG SIDEBAR ORPHAN].freeze
+
+    class << self
+      def render(diagnostics:, current_file:, sse_port:)
+        return "" if diagnostics.empty?
+
+        attrs = build_data_attributes(diagnostics, current_file, sse_port)
+        render_overlay_html(attrs)
+      end
+
+      private
+
+      def build_data_attributes(diagnostics, current_file, sse_port)
+        global_count = diagnostics.count { |d| GLOBAL_CATEGORIES.include?(d.category) }
+        page_count = diagnostics.length - global_count
+
+        {
+          diagnostics: escape_json(diagnostics),
+          current_file: escape_html(current_file),
+          error_count: diagnostics.count(&:error?),
+          warning_count: diagnostics.count(&:warning?),
+          global_count: global_count,
+          page_count: page_count,
+          sse_port: sse_port,
+          editor_available: EditorLauncher.available?
+        }
+      end
+
+      def render_overlay_html(attrs)
+        <<~HTML
+          <div id="docyard-error-overlay" class="docyard-error-overlay"
+               data-diagnostics='#{attrs[:diagnostics]}'
+               data-current-file="#{attrs[:current_file]}"
+               data-error-count="#{attrs[:error_count]}"
+               data-warning-count="#{attrs[:warning_count]}"
+               data-global-count="#{attrs[:global_count]}"
+               data-page-count="#{attrs[:page_count]}"
+               data-sse-port="#{attrs[:sse_port]}"
+               data-editor-available="#{attrs[:editor_available]}">
+          </div>
+          <link rel="stylesheet" href="/_docyard/error-overlay.css">
+          <script src="/_docyard/error-overlay.js"></script>
+        HTML
+      end
+
+      def escape_json(diagnostics)
+        JSON.generate(diagnostics.map(&:to_h)).gsub("'", "&#39;")
+      end
+
+      def escape_html(str)
+        str.to_s.gsub("&", "&amp;").gsub('"', "&quot;").gsub("<", "&lt;").gsub(">", "&gt;")
+      end
+    end
+  end
+end

data/lib/docyard/server/file_watcher.rb

@@ -5,7 +5,6 @@ require "listen"
 module Docyard
   class FileWatcher
     DEBOUNCE_DELAY = 0.1
-    ROOT_CONFIG_FILE = "docyard.yml"
     CONFIG_FILES = %w[docyard.yml _sidebar.yml].freeze
     CONTENT_EXTENSIONS = %w[.md .markdown].freeze
     ASSET_EXTENSIONS = %w[.css .js .html .erb].freeze

data/lib/docyard/server/page_diagnostics.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../doctor/content_checker"
+require_relative "../doctor/component_checker"
+require_relative "../doctor/link_checker"
+require_relative "../doctor/image_checker"
+
+module Docyard
+  class PageDiagnostics
+    def initialize(docs_path)
+      @docs_path = docs_path
+      @content_checker = Doctor::ContentChecker.new(docs_path)
+      @component_checker = Doctor::ComponentChecker.new(docs_path)
+      @link_checker = Doctor::LinkChecker.new(docs_path)
+      @image_checker = Doctor::ImageChecker.new(docs_path)
+    end
+
+    def check(content, file_path)
+      [
+        @content_checker.check_file(content, file_path),
+        @component_checker.check_file(content, file_path),
+        @link_checker.check_file(content, file_path),
+        @image_checker.check_file(content, file_path)
+      ].flatten
+    end
+  end
+end

data/lib/docyard/server/preview_server.rb

@@ -9,14 +9,17 @@ require_relative "static_file_app"
 
 module Docyard
   class PreviewServer
+    include Utils::UrlHelpers
+
     DEFAULT_PORT = 4000
 
-    attr_reader :port, :output_dir
+    attr_reader :port, :output_dir, :base_url
 
     def initialize(port: DEFAULT_PORT)
       @port = port
       @config = Config.load
       @output_dir = File.expand_path(@config.build.output)
+      @base_url = normalize_base_url(@config.build.base)
       @launcher = nil
     end
 
@@ -29,21 +32,30 @@ module Docyard
     private
 
     def validate_output_directory!
-      return if File.directory?(output_dir)
+      unless File.directory?(output_dir)
+        abort "#{UI.error('Error:')} #{output_dir}/ directory not found.\n" \
+              "Run `docyard build` first to build the site."
+      end
+
+      return if Dir.glob(File.join(output_dir, "**", "*")).any? { |f| File.file?(f) }
 
-      abort "Error: #{output_dir}/ directory not found.\n" \
+      abort "#{UI.error('Error:')} #{output_dir}/ is empty.\n" \
             "Run `docyard build` first to build the site."
     end
 
     def print_server_info
-      Docyard.logger.info("Starting preview server...")
-      Docyard.logger.info("* Version: #{Docyard::VERSION}")
-      Docyard.logger.info("* Running at: http://localhost:#{port}")
-      Docyard.logger.info("Use Ctrl+C to stop\n")
+      puts
+      puts "  #{UI.bold('Docyard')} v#{Docyard::VERSION}"
+      puts
+      puts "  Previewing #{output_dir}/"
+      puts "  #{UI.cyan("http://localhost:#{port}#{base_url}")}"
+      puts
+      puts "  #{UI.dim('Press Ctrl+C to stop')}"
+      puts
     end
 
     def run_server
-      app = StaticFileApp.new(output_dir)
+      app = StaticFileApp.new(output_dir, base_path: base_url)
       puma_config = build_puma_config(app)
       log_writer = Puma::LogWriter.strings
 

data/lib/docyard/server/rack_application.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
 require "rack"
 require_relative "../navigation/page_navigation_builder"
 require_relative "../navigation/sidebar_builder"
@@ -9,20 +8,29 @@ require_relative "../constants"
 require_relative "../rendering/template_resolver"
 require_relative "../routing/fallback_resolver"
 require_relative "pagefind_handler"
+require_relative "page_diagnostics"
+require_relative "error_overlay"
+require_relative "../editor_launcher"
 
 module Docyard
   class RackApplication
-    def initialize(docs_path:, config: nil, pagefind_path: nil, sse_port: nil, sidebar_cache: nil)
+    OVERLAY_RESET_SCRIPT = "<script>try{sessionStorage.setItem('docyard-error-overlay'," \
+                           "'{\"dismissed\":false,\"lastTotalCount\":0}')}catch(e){}</script>"
+
+    def initialize(docs_path:, config: nil, pagefind_path: nil, sse_port: nil, sidebar_cache: nil,
+                   global_diagnostics: [])
       @docs_path = docs_path
       @config = config
       @sse_port = sse_port
       @dev_mode = !sse_port.nil?
       @sidebar_cache = sidebar_cache
+      @global_diagnostics = global_diagnostics
       @router = Router.new(docs_path: docs_path)
       @renderer = Renderer.new(base_url: "/", config: config, dev_mode: @dev_mode,
                                sse_port: sse_port)
       @asset_handler = AssetHandler.new(public_dir: config&.public_dir || "docs/public")
       @pagefind_handler = PagefindHandler.new(pagefind_path: pagefind_path, config: config)
+      @page_diagnostics = PageDiagnostics.new(docs_path) if @dev_mode
     end
 
     def call(env)
@@ -36,6 +44,8 @@ module Docyard
     def handle_request(env)
       path = env["PATH_INFO"]
 
+      return handle_open_in_editor(env) if path == "/__docyard/open-in-editor"
+      return serve_overlay_asset(path) if path.start_with?("/_docyard/error-overlay")
       return pagefind_handler.serve(path) if path.start_with?(Constants::PAGEFIND_PREFIX)
       return asset_handler.serve_docyard_assets(path) if path.start_with?(Constants::DOCYARD_ASSETS_PREFIX)
 
@@ -94,7 +104,8 @@ module Docyard
     end
 
     def render_documentation_page(file_path, current_path)
-      markdown = Markdown.new(File.read(file_path))
+      content = File.read(file_path)
+      markdown = Markdown.new(content)
       template_resolver = TemplateResolver.new(markdown.frontmatter, @config&.data)
       branding = branding_options
 
@@ -103,6 +114,8 @@ module Docyard
                                                            template_options: template_resolver.to_options,
                                                            current_path: current_path)
 
+      html = inject_error_overlay(html, content, file_path) if dev_mode
+
       [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
     end
 
@@ -156,5 +169,53 @@ module Docyard
       user_agent = env["HTTP_USER_AGENT"]&.slice(0, 50)
       user_agent ? "#{method} #{path} - #{user_agent}" : "#{method} #{path}"
     end
+
+    def inject_error_overlay(html, content, file_path)
+      page_diags = @page_diagnostics.check(content, file_path)
+      all_diagnostics = @global_diagnostics + page_diags
+      return html.sub("</body>", "#{OVERLAY_RESET_SCRIPT}</body>") if all_diagnostics.empty?
+
+      current_file = file_path.delete_prefix("#{@docs_path}/")
+      overlay = ErrorOverlay.render(
+        diagnostics: all_diagnostics,
+        current_file: current_file,
+        sse_port: @sse_port
+      )
+
+      html.sub("</body>", "#{overlay}</body>")
+    end
+
+    def handle_open_in_editor(env)
+      params = Rack::Utils.parse_query(env["QUERY_STRING"])
+      file = params["file"]
+      line = params["line"]&.to_i || 1
+
+      return [400, {}, ["Missing file parameter"]] unless file
+      return [404, {}, ["No editor detected"]] unless EditorLauncher.available?
+
+      full_path = File.join(@docs_path, file)
+      EditorLauncher.open(full_path, line)
+      [200, {}, ["OK"]]
+    end
+
+    def serve_overlay_asset(path)
+      asset_path = resolve_overlay_asset_path(path)
+      return [404, {}, ["Not found"]] unless asset_path && File.exist?(asset_path)
+
+      content_type = path.end_with?(".css") ? "text/css" : "application/javascript"
+      [200, { "Content-Type" => content_type }, [File.read(asset_path)]]
+    end
+
+    def resolve_overlay_asset_path(path)
+      asset_name = path.delete_prefix("/_docyard/")
+      css_path = File.join(templates_path, "assets", asset_name.sub("error-overlay", "css/error-overlay"))
+      return css_path if File.exist?(css_path)
+
+      File.join(templates_path, "assets", asset_name.sub("error-overlay", "js/error-overlay"))
+    end
+
+    def templates_path
+      File.expand_path("../templates", __dir__)
+    end
   end
 end

data/lib/docyard/server/resolution_result.rb

@@ -21,9 +21,5 @@ module Docyard
     def found?
       status == :found
     end
-
-    def not_found?
-      status == :not_found
-    end
   end
 end

data/lib/docyard/server/static_file_app.rb

@@ -4,15 +4,20 @@ require "rack/mime"
 
 module Docyard
   class StaticFileApp
-    def initialize(root)
+    def initialize(root, base_path: "/")
       @root = root
+      @base_path = base_path.chomp("/")
     end
 
     def call(env)
       path = env["PATH_INFO"]
-      file_path = File.join(@root, path)
 
-      if path.end_with?("/") || File.directory?(file_path)
+      return serve_not_found unless path_under_base?(path)
+
+      relative_path = strip_base_path(path)
+      file_path = File.join(@root, relative_path)
+
+      if relative_path.end_with?("/") || relative_path.empty? || File.directory?(file_path)
         index_path = File.join(file_path, "index.html")
         return serve_file(index_path) if File.file?(index_path)
       elsif File.file?(file_path)
@@ -24,6 +29,18 @@ module Docyard
 
     private
 
+    def path_under_base?(path)
+      return true if @base_path.empty?
+
+      path == @base_path || path.start_with?("#{@base_path}/")
+    end
+
+    def strip_base_path(path)
+      return path if @base_path.empty?
+
+      path.delete_prefix(@base_path)
+    end
+
     def serve_file(path)
       content = File.read(path)
       content_type = Rack::Mime.mime_type(File.extname(path), "application/octet-stream")