docyard 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69c121af95a08c379f260d0d444aa4bc5272fdfe2d0699866091885c9f503601
-  data.tar.gz: 4550cdcc1d6863b545c4900aac9adb10f14d96a7394ccd3fe4c8924969b278dc
+  metadata.gz: a6ab36d72a5ae740f0ba203c29ab88b2698f0010bbc980ac0ef3a8b7d5f9f579
+  data.tar.gz: f4df0ae89a078729eb319733ac7dab36943fa9e228daaba9fb75e6323a2f6fab
 SHA512:
-  metadata.gz: 690e11d0792b71540f09d26fe45dc46d57558b3aad1b3cf80f3e08c592a4056408b6b8a57bfc47f2459feba94e481038f11ccef287534a9f82e557c255728b53
-  data.tar.gz: 8baa1a707f2ff94152499b66c19596a57984c5ff763d2cf43390d986030e2e2eea994febac3089766a764ec1d6314a61479fe2caa54434ee5e64c86ade6431e1
+  metadata.gz: 4c4e05cb41cf1259a74a73c24c45fa265da9fbaf6725905e9893f442e9e1a2dbf1979ba03c5aac030bafd9e2f574fa0fec50f1f11ee5fd583353e3fd7b8329ea
+  data.tar.gz: f53424206fd8224b815232c4c2babca237852829f4f43f8fe537f63136c65e7b25ae75d6276a4b07416b4c24cc8274b822946c6f03a2e6aa2c6f394cc5334327

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-01-30
+
+### Added
+- **Doctor Command** - Health check CLI with `docyard doctor` to find broken links, missing images, orphan pages, and config issues (#135)
+- **Auto-fix** - Automatically fix common issues with `docyard doctor --fix` including typos, string booleans, and missing slashes (#135)
+- **Config Validation** - Validate `docyard.yml` and `_sidebar.yml` with helpful error messages and suggestions (#138)
+- **Dev Server Error Overlay** - Bottom sheet overlay showing errors with syntax-highlighted code snippets, line numbers, and clickable file paths (#143)
+- **Strict Mode** - Fail builds on validation errors with `--strict` flag or `build.strict` config (#143)
+- **Colored CLI Output** - ANSI colors for better readability with `--no-color` flag and `NO_COLOR` env support (#142)
+- **CLI Progress Spinners** - Animated spinners and step-by-step progress display for build and serve commands (#136)
+- **Verbose Timing Breakdown** - Per-page timing in `docyard build --verbose` output (#141)
+
+### Fixed
+- "Last updated" timestamps now calculate relative time client-side for accurate display (#134)
+
+### Changed
+- Build output format updated with progress indicators (#136, #141)
+- Config validation now runs on every build (#138)
+
+### Documentation
+- Added `docyard doctor` command reference
+- Added strict mode documentation to CLI and configuration references
+- Added error overlay mention to dev server documentation
+- Updated build output examples to match current format
+
 ## [1.0.2] - 2026-01-23
 
 ### Fixed
@@ -224,7 +249,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/v1.0.2...HEAD
+[Unreleased]: https://github.com/sanifhimani/docyard/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/sanifhimani/docyard/compare/v1.0.2...v1.1.0
 [1.0.2]: https://github.com/sanifhimani/docyard/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/sanifhimani/docyard/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/sanifhimani/docyard/compare/v0.9.0...v1.0.0

data/lib/docyard/build/asset_bundler.rb

@@ -7,6 +7,8 @@ require "digest"
 module Docyard
   module Build
     class AssetBundler
+      include Utils::UrlHelpers
+
       ASSETS_PATH = File.join(__dir__, "..", "templates", "assets")
 
       attr_reader :config, :verbose
@@ -17,21 +19,17 @@ module Docyard
       end
 
       def bundle
-        Docyard.logger.info("\nBundling assets...")
-
-        css_hash = bundle_css
-        js_hash = bundle_js
+        css_hash, css_size = bundle_css
+        js_hash, js_size = bundle_js
 
         update_html_references(css_hash, js_hash)
 
-        2
+        [css_size, js_size]
       end
 
       private
 
       def bundle_css
-        log "  Bundling CSS..."
-
         main_css = File.read(File.join(ASSETS_PATH, "css", "main.css"))
         css_content = resolve_css_imports(main_css)
         minified = CSSminify.compress(css_content)
@@ -41,9 +39,8 @@ module Docyard
         hash = generate_hash(minified)
 
         write_bundled_asset(minified, hash, "css")
-        log_compression_stats(css_content, minified, "CSS")
 
-        hash
+        [hash, minified.bytesize]
       end
 
       def fix_calc_whitespace(css)
@@ -86,8 +83,6 @@ module Docyard
       end
 
       def bundle_js
-        log "  Bundling JS..."
-
         theme_js = File.read(File.join(ASSETS_PATH, "js", "theme.js"))
         components_js = concatenate_component_js
         js_content = [theme_js, components_js].join("\n")
@@ -96,9 +91,8 @@ module Docyard
         hash = generate_hash(minified)
 
         write_bundled_asset(minified, hash, "js")
-        log_compression_stats(js_content, minified, "JS")
 
-        hash
+        [hash, minified.bytesize]
       end
 
       def replace_js_asset_urls(js_content)
@@ -127,8 +121,6 @@ module Docyard
           content = replace_asset_references(File.read(file), css_hash, js_hash, base_url)
           File.write(file, content)
         end
-
-        log "  [✓] Updated asset references in #{html_files.size} HTML files"
       end
 
       def replace_asset_references(content, css_hash, js_hash, base_url)
@@ -154,24 +146,6 @@ module Docyard
         FileUtils.mkdir_p(File.dirname(output_path))
         File.write(output_path, content)
       end
-
-      def log_compression_stats(original, minified, label)
-        original_size = (original.bytesize / 1024.0).round(1)
-        minified_size = (minified.bytesize / 1024.0).round(1)
-        reduction = (((original_size - minified_size) / original_size) * 100).round(0)
-        log "  [✓] #{label}: #{original_size} KB -> #{minified_size} KB (-#{reduction}%)"
-      end
-
-      def normalize_base_url(url)
-        return "/" if url.nil? || url.empty? || url == "/"
-
-        url = "/#{url}" unless url.start_with?("/")
-        url.end_with?("/") ? url : "#{url}/"
-      end
-
-      def log(message)
-        Docyard.logger.info(message)
-      end
     end
   end
 end

data/lib/docyard/build/file_copier.rb

@@ -13,14 +13,12 @@ module Docyard
       end
 
       def copy
-        Docyard.logger.info("\nCopying static assets...")
-
+        @copied_files = []
         count = 0
         count += copy_public_files
         count += copy_branding_assets
-
-        log "[✓] Copied #{count} static files"
-        count
+        details = verbose ? @copied_files : nil
+        [count, details]
       end
 
       private
@@ -32,7 +30,6 @@ module Docyard
         files = find_files_in_dir(public_dir)
         files.each { |file| copy_single_file(file, "#{public_dir}/", config.build.output) }
 
-        log "[✓] Copied #{files.size} public files from #{public_dir}/" if files.any?
         files.size
       end
 
@@ -47,14 +44,13 @@ module Docyard
         FileUtils.mkdir_p(File.dirname(dest_path))
         FileUtils.cp(file, dest_path)
 
-        log "  Copied: #{relative_path}" if verbose
+        @copied_files << relative_path if verbose
       end
 
       def copy_branding_assets
         count = 0
         count += copy_default_branding_assets
         count += copy_user_branding_assets
-        log "[✓] Copied #{count} branding assets" if count.positive?
         count
       end
 
@@ -80,7 +76,7 @@ module Docyard
         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
+        @copied_files << "#{filename} (#{label})" if verbose
         1
       end
 
@@ -96,7 +92,7 @@ module Docyard
         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
+        @copied_files << "#{File.basename(font_file)} (font)" if verbose
         1
       end
 
@@ -122,13 +118,9 @@ module Docyard
         FileUtils.mkdir_p(File.dirname(dest_path))
         FileUtils.cp(full_path, dest_path)
 
-        log "  Copied user branding: #{asset_path}" if verbose
+        @copied_files << "#{asset_path} (user branding)" if verbose
         1
       end
-
-      def log(message)
-        Docyard.logger.info(message)
-      end
     end
   end
 end

data/lib/docyard/build/llms_txt_generator.rb

@@ -50,7 +50,6 @@ module Docyard
       def generate_llms_txt(pages)
         output_path = File.join(config.build.output, "llms.txt")
         File.write(output_path, build_llms_txt_content(pages))
-        Docyard.logger.info("[✓] Generated llms.txt (#{pages.size} pages)")
       end
 
       def build_llms_txt_content(pages)
@@ -70,7 +69,6 @@ module Docyard
       def generate_llms_full_txt(pages)
         output_path = File.join(config.build.output, "llms-full.txt")
         File.write(output_path, build_llms_full_txt_content(pages))
-        Docyard.logger.info("[✓] Generated llms-full.txt")
       end
 
       def build_llms_full_txt_content(pages)

data/lib/docyard/build/sitemap_generator.rb

@@ -18,7 +18,7 @@ module Docyard
         output_path = File.join(config.build.output, "sitemap.xml")
         File.write(output_path, sitemap_content)
 
-        Docyard.logger.info("[✓] Generated sitemap.xml (#{urls.size} URLs)")
+        urls.size
       end
 
       private

data/lib/docyard/build/static_generator.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "parallel"
-require "tty-progressbar"
 require_relative "../rendering/template_resolver"
 require_relative "../navigation/page_navigation_builder"
 require_relative "../navigation/sidebar/cache"
@@ -32,13 +31,11 @@ module Docyard
         copy_custom_landing_page if custom_landing_page?
 
         markdown_files = collect_markdown_files
-        Docyard.logger.info("\n[✓] Found #{markdown_files.size} markdown files")
-
-        generate_all_pages(markdown_files)
+        generated_pages = generate_all_pages(markdown_files)
         generate_error_page
         generate_root_fallback_if_needed
 
-        markdown_files.size
+        [markdown_files.size, build_verbose_details(generated_pages)]
       ensure
         Utils::GitInfo.clear_cache
       end
@@ -46,20 +43,14 @@ module Docyard
       private
 
       def generate_all_pages(markdown_files)
-        progress = TTY::ProgressBar.new(
-          "Generating pages [:bar] :current/:total (:percent)",
-          total: markdown_files.size,
-          width: 50
-        )
-        mutex = Mutex.new
-
         Logging.start_buffering
-        if markdown_files.size >= PARALLEL_THRESHOLD
-          generate_pages_in_parallel(markdown_files, progress, mutex)
-        else
-          generate_pages_sequentially(markdown_files, progress)
-        end
+        pages = if markdown_files.size >= PARALLEL_THRESHOLD
+                  generate_pages_in_parallel(markdown_files)
+                else
+                  generate_pages_sequentially(markdown_files)
+                end
         Logging.flush_warnings
+        pages
       end
 
       def custom_landing_page?
@@ -72,7 +63,6 @@ module Docyard
           FileUtils.mkdir_p(File.dirname(output_path))
           FileUtils.cp(File.join(docs_path, "index.html"), output_path)
         end
-        log "[✓] Copied custom landing page (index.html)"
       end
 
       def collect_markdown_files
@@ -81,23 +71,28 @@ module Docyard
         files
       end
 
-      def generate_pages_in_parallel(markdown_files, progress, mutex)
-        Parallel.each(markdown_files, in_threads: Parallel.processor_count) do |file_path|
-          generate_page(file_path, thread_local_renderer)
-          mutex.synchronize { progress.advance }
+      def generate_pages_in_parallel(markdown_files)
+        Parallel.map(markdown_files, in_threads: Parallel.processor_count) do |file_path|
+          generate_page_with_timing(file_path, thread_local_renderer)
         ensure
           Thread.current[:docyard_build_renderer] = nil
         end
       end
 
-      def generate_pages_sequentially(markdown_files, progress)
+      def generate_pages_sequentially(markdown_files)
         renderer = build_renderer
-        markdown_files.each do |file_path|
-          generate_page(file_path, renderer)
-          progress.advance
+        markdown_files.map do |file_path|
+          generate_page_with_timing(file_path, renderer)
         end
       end
 
+      def generate_page_with_timing(file_path, renderer)
+        page_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        output_path = generate_page(file_path, renderer)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - page_start
+        [output_path, elapsed]
+      end
+
       def thread_local_renderer
         Thread.current[:docyard_build_renderer] ||= build_renderer
       end
@@ -114,6 +109,7 @@ module Docyard
         html_content = render_markdown_file(markdown_file_path, current_path, renderer)
         html_content = apply_search_exclusion(html_content, current_path)
         write_output(output_path, html_content)
+        output_path
       end
 
       def apply_search_exclusion(html_content, current_path)
@@ -165,7 +161,6 @@ module Docyard
           FileUtils.mkdir_p(File.dirname(output_path))
           File.write(output_path, html_content)
         end
-        log "Generated: #{output_path}" if verbose
       end
 
       def build_sidebar_cache
@@ -184,8 +179,13 @@ module Docyard
         config.source
       end
 
-      def log(message)
-        Docyard.logger.info(message) if verbose
+      def build_verbose_details(generated_pages)
+        return nil unless verbose
+
+        generated_pages.map do |output_path, elapsed|
+          path = output_path.delete_prefix("#{config.build.output}/")
+          "#{path.ljust(30)} #{format('%<t>.2fs', t: elapsed)}"
+        end
       end
 
       def generate_error_page
@@ -194,7 +194,6 @@ module Docyard
           docs_path: docs_path,
           renderer: build_renderer
         ).generate
-        log "[✓] Generated 404.html"
       end
 
       def generate_root_fallback_if_needed
@@ -204,8 +203,7 @@ module Docyard
           sidebar_cache: sidebar_cache,
           renderer: build_renderer
         )
-        target = generator.generate_if_needed
-        log "[✓] Generated root redirect to #{target}" if target
+        generator.generate_if_needed
       end
     end
   end

data/lib/docyard/build/step_runner.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Build
+    class StepRunner
+      STEP_SHORT_LABELS = {
+        "Generating pages" => "Pages",
+        "Bundling assets" => "Assets",
+        "Copying files" => "Files",
+        "Generating SEO" => "SEO",
+        "Indexing search" => "Search"
+      }.freeze
+
+      attr_reader :verbose, :step_timings
+
+      def initialize(verbose: false)
+        @verbose = verbose
+        @step_timings = []
+      end
+
+      def run(label, &)
+        print "  #{label.ljust(20)}#{UI.dim('in progress')}"
+        $stdout.flush
+        result, details, elapsed = execute(label, &)
+        print_result(label, result, elapsed)
+        print_details(details) if verbose && details&.any?
+        result
+      end
+
+      def print_timing_breakdown
+        total = step_timings.sum { |t| t[:elapsed] }
+        sorted = step_timings.sort_by { |t| -t[:elapsed] }
+
+        puts "  #{UI.bold('Timing:')}"
+        sorted.each { |timing| puts "    #{UI.dim(format_timing_line(timing, total))}" }
+        puts
+      end
+
+      private
+
+      def execute(label)
+        step_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result, details = yield
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - step_start
+        @step_timings << { label: STEP_SHORT_LABELS.fetch(label, label), elapsed: elapsed }
+        [result, details, elapsed]
+      end
+
+      def print_result(label, result, elapsed)
+        timing_suffix = verbose ? UI.dim(" in #{format('%<t>.2fs', t: elapsed)}") : ""
+        print "\r  #{label.ljust(20)}#{UI.green(format_result(label, result))}#{timing_suffix}\n"
+        $stdout.flush
+      end
+
+      def print_details(details)
+        details.each { |detail| puts "      #{UI.dim(detail)}" }
+      end
+
+      def format_result(label, result)
+        case label
+        when "Generating pages" then "done (#{result} pages)"
+        when "Bundling assets" then format_assets_result(result)
+        when "Copying files" then "done (#{result} files)"
+        when "Generating SEO" then "done (#{result.join(', ')})"
+        when "Indexing search" then "done (#{result} pages indexed)"
+        else "done"
+        end
+      end
+
+      def format_assets_result(result)
+        css, js = result
+        "done (#{format_size(css)} CSS, #{format_size(js)} JS)"
+      end
+
+      def format_size(bytes)
+        kb = bytes / 1024.0
+        kb >= 1000 ? format("%.1f MB", kb / 1024.0) : format("%.1f KB", kb)
+      end
+
+      def format_timing_line(timing, total)
+        label = timing[:label].ljust(12)
+        secs = format("%<t>5.2fs", t: timing[:elapsed])
+        pct = total.positive? ? (timing[:elapsed] / total * 100).round : 0
+        "#{label} #{secs} (#{format('%<p>2d', p: pct)}%)"
+      end
+    end
+  end
+end

data/lib/docyard/build/validator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Build
+    class Validator
+      attr_reader :config, :strict, :diagnostics
+
+      def initialize(config, strict: false)
+        @config = config
+        @strict = strict
+        @diagnostics = []
+      end
+
+      def valid?
+        @diagnostics = collect_diagnostics
+        failing_diagnostics.empty?
+      end
+
+      def errors
+        diagnostics.select(&:error?)
+      end
+
+      def failing_diagnostics
+        strict ? diagnostics : errors
+      end
+
+      def warnings
+        diagnostics.select(&:warning?)
+      end
+
+      def print_errors(context: "Build")
+        return if failing_diagnostics.empty?
+
+        print_header
+        puts "  #{UI.red("#{context} failed due to validation errors:")}"
+        puts
+        failing_diagnostics.each { |d| puts format_diagnostic_line(d) }
+        puts
+      end
+
+      def print_warnings
+        return if warnings.empty?
+
+        puts
+        puts "  #{UI.yellow("#{warnings.size} warning(s) found:")}"
+        warnings.each { |d| puts "    #{UI.yellow('warn ')}  #{d.location.ljust(26)} #{d.message}" }
+        puts
+      end
+
+      private
+
+      def print_header
+        puts
+        puts "  #{UI.bold('Docyard')} v#{VERSION}"
+        puts
+      end
+
+      def format_diagnostic_line(diagnostic)
+        if diagnostic.error?
+          "    #{UI.red('error')}  #{diagnostic.location.ljust(26)} #{diagnostic.message}"
+        else
+          "    #{UI.yellow('warn ')}  #{diagnostic.location.ljust(26)} #{diagnostic.message}"
+        end
+      end
+
+      def collect_diagnostics
+        strict ? collect_strict_diagnostics : collect_essential_diagnostics
+      end
+
+      def collect_essential_diagnostics
+        require_relative "../doctor/config_checker"
+        require_relative "../doctor/sidebar_checker"
+
+        [
+          Doctor::ConfigChecker.new(config).check,
+          Doctor::SidebarChecker.new(docs_path).check
+        ].flatten
+      end
+
+      def collect_strict_diagnostics
+        require_relative "../doctor"
+
+        file_scanner = Doctor::FileScanner.new(docs_path)
+        scanner_diagnostics = file_scanner.scan
+
+        [
+          collect_essential_diagnostics,
+          scanner_diagnostics,
+          Doctor::OrphanChecker.new(docs_path, config).check
+        ].flatten
+      end
+
+      def docs_path
+        config.source
+      end
+    end
+  end
+end