docyard 0.9.0 → 1.0.0

data/lib/docyard/build/static_generator.rb

@@ -1,65 +1,111 @@
 # frozen_string_literal: true
 
+require "parallel"
 require "tty-progressbar"
 require_relative "../rendering/template_resolver"
-require_relative "../navigation/prev_next_builder"
-require_relative "../navigation/breadcrumb_builder"
+require_relative "../navigation/page_navigation_builder"
+require_relative "../navigation/sidebar/cache"
+require_relative "../utils/path_utils"
+require_relative "../utils/git_info"
 
 module Docyard
   module Build
     class StaticGenerator
-      attr_reader :config, :verbose, :renderer
+      PARALLEL_THRESHOLD = 10
+
+      attr_reader :config, :verbose, :sidebar_cache
 
       def initialize(config, verbose: false)
         @config = config
         @verbose = verbose
-        @renderer = Renderer.new(base_url: config.build.base, config: config)
+        @sidebar_cache = nil
       end
 
       def generate
+        build_sidebar_cache
+        Utils::GitInfo.prefetch_timestamps(docs_path) if show_last_updated?
         copy_custom_landing_page if custom_landing_page?
 
         markdown_files = collect_markdown_files
-        puts "\n[✓] Found #{markdown_files.size} markdown files"
+        Docyard.logger.info("\n[✓] Found #{markdown_files.size} markdown files")
+
+        generate_all_pages(markdown_files)
+        generate_error_page
+
+        markdown_files.size
+      ensure
+        Utils::GitInfo.clear_cache
+      end
+
+      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
 
-        markdown_files.each do |file_path|
-          generate_page(file_path)
-          progress.advance
+        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
-
-        markdown_files.size
+        Logging.flush_warnings
       end
 
-      private
-
       def custom_landing_page?
-        File.file?("docs/index.html")
+        File.file?(File.join(docs_path, "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)
+        safe_file_write(output_path) do
+          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
-        files = Dir.glob(File.join("docs", "**", "*.md"))
-        files.reject! { |f| f == "docs/index.md" } if custom_landing_page?
+        files = Dir.glob(File.join(docs_path, "**", "*.md"))
+        files.reject! { |f| f == File.join(docs_path, "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)
+      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 }
+        ensure
+          Thread.current[:docyard_build_renderer] = nil
+        end
+      end
+
+      def generate_pages_sequentially(markdown_files, progress)
+        renderer = build_renderer
+        markdown_files.each do |file_path|
+          generate_page(file_path, renderer)
+          progress.advance
+        end
+      end
+
+      def thread_local_renderer
+        Thread.current[:docyard_build_renderer] ||= build_renderer
+      end
+
+      def build_renderer
+        Renderer.new(base_url: config.build.base, config: config)
+      end
+
+      def generate_page(markdown_file_path, renderer)
+        relative_path = markdown_file_path.delete_prefix("#{docs_path}/")
+        output_path = Utils::PathUtils.markdown_to_html_output(relative_path, config.build.output)
+        current_path = Utils::PathUtils.markdown_file_to_url(markdown_file_path, docs_path)
 
-        html_content = render_markdown_file(markdown_file_path, current_path)
+        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)
       end
@@ -79,10 +125,10 @@ module Docyard
         end
       end
 
-      def render_markdown_file(markdown_file_path, current_path)
+      def render_markdown_file(markdown_file_path, current_path, renderer)
         markdown = Markdown.new(File.read(markdown_file_path))
         template_resolver = TemplateResolver.new(markdown.frontmatter, config.data)
-        branding = branding_options
+        branding = BrandingResolver.new(config).resolve
 
         navigation = build_navigation_html(template_resolver, current_path, markdown, branding[:header_ctas])
         renderer.render_file(markdown_file_path, **navigation, branding: branding,
@@ -91,82 +137,72 @@ module Docyard
       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)
-        }
+        navigation_builder.build(
+          current_path: current_path,
+          markdown: markdown,
+          header_ctas: header_ctas,
+          show_sidebar: template_resolver.show_sidebar?
+        )
       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
+      def navigation_builder
+        @navigation_builder ||= Navigation::PageNavigationBuilder.new(
+          docs_path: docs_path,
+          config: config,
+          sidebar_cache: sidebar_cache
+        )
       end
 
-      def determine_output_path(markdown_file_path)
-        relative_path = markdown_file_path.delete_prefix("docs/")
-        base_name = File.basename(relative_path, ".md")
-        dir_name = File.dirname(relative_path)
-
-        output_dir = config.build.output
-
-        if base_name == "index"
-          File.join(output_dir, dir_name, "index.html")
-        else
-          File.join(output_dir, dir_name, base_name, "index.html")
+      def write_output(output_path, html_content)
+        safe_file_write(output_path) do
+          FileUtils.mkdir_p(File.dirname(output_path))
+          File.write(output_path, html_content)
         end
+        log "Generated: #{output_path}" if verbose
       end
 
-      def determine_current_path(markdown_file_path)
-        relative_path = markdown_file_path.delete_prefix("docs/")
-        base_name = File.basename(relative_path, ".md")
-        dir_name = File.dirname(relative_path)
-
-        if base_name == "index"
-          dir_name == "." ? "/" : "/#{dir_name}"
-        else
-          dir_name == "." ? "/#{base_name}" : "/#{dir_name}/#{base_name}"
-        end
+      def safe_file_write(path, &block)
+        block.call
+      rescue Errno::EACCES => e
+        raise BuildError, "Permission denied writing to #{path}: #{e.message}"
+      rescue Errno::ENOSPC => e
+        raise BuildError, "Disk full, cannot write to #{path}: #{e.message}"
+      rescue Errno::EROFS => e
+        raise BuildError, "Read-only filesystem, cannot write to #{path}: #{e.message}"
+      rescue SystemCallError => e
+        raise BuildError, "Failed to write #{path}: #{e.message}"
       end
 
-      def build_sidebar_instance(current_path, header_ctas = [])
-        SidebarBuilder.new(
-          docs_path: "docs",
-          current_path: current_path,
-          config: config,
-          header_ctas: header_ctas
+      def build_sidebar_cache
+        @sidebar_cache = Sidebar::Cache.new(
+          docs_path: docs_path,
+          config: config
         )
+        @sidebar_cache.build
       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
+      def show_last_updated?
+        config.repo.url && config.repo.last_updated != false
       end
 
-      def build_breadcrumbs(sidebar_tree, current_path)
-        return nil unless breadcrumbs_enabled?
-
-        BreadcrumbBuilder.new(sidebar_tree: sidebar_tree, current_path: current_path)
+      def docs_path
+        config.source
       end
 
-      def breadcrumbs_enabled?
-        config.navigation.breadcrumbs != false
+      def log(message)
+        Docyard.logger.info(message) if verbose
       end
 
-      def branding_options
-        BrandingResolver.new(config).resolve
+      def generate_error_page
+        output_path = File.join(config.build.output, "404.html")
+        html_content = load_error_page_content
+        safe_file_write(output_path) { File.write(output_path, html_content) }
+        log "[✓] Generated 404.html"
       end
 
-      def log(message)
-        puts message if verbose
+      def load_error_page_content
+        error_page = File.join(docs_path, "404.html")
+        File.exist?(error_page) ? File.read(error_page) : build_renderer.render_not_found
       end
     end
   end

data/lib/docyard/builder.rb

@@ -68,6 +68,10 @@ module Docyard
       sitemap_gen = Build::SitemapGenerator.new(config)
       sitemap_gen.generate
 
+      require_relative "build/llms_txt_generator"
+      llms_gen = Build::LlmsTxtGenerator.new(config)
+      llms_gen.generate
+
       File.write(File.join(config.build.output, "robots.txt"), robots_txt_content)
       log "[+] Generated robots.txt"
     end
@@ -104,11 +108,11 @@ module Docyard
     end
 
     def log(message)
-      puts message
+      Docyard.logger.info(message)
     end
 
     def error(message)
-      warn "[ERROR] #{message}"
+      Docyard.logger.error(message)
     end
   end
 end

data/lib/docyard/cli.rb

@@ -13,9 +13,11 @@ module Docyard
       puts "docyard #{Docyard::VERSION}"
     end
 
-    desc "init", "Initialize a new docyard project"
-    def init
-      initializer = Docyard::Initializer.new
+    desc "init [PROJECT_NAME]", "Initialize a new docyard project"
+    method_option :force, type: :boolean, default: false, aliases: "-f",
+                          desc: "Overwrite existing files"
+    def init(project_name = nil)
+      initializer = Docyard::Initializer.new(project_name, force: options[:force])
       exit(1) unless initializer.run
     end
 
@@ -29,6 +31,9 @@ module Docyard
         verbose: options[:verbose]
       )
       exit(1) unless builder.build
+    rescue ConfigError => e
+      Docyard.logger.error(e.message)
+      exit(1)
     end
 
     desc "preview", "Preview the built site locally"
@@ -45,12 +50,17 @@ module Docyard
                            desc: "Enable search indexing (slower startup)"
     def serve
       require_relative "server/dev_server"
-      server = Docyard::Server.new(
+      config = Docyard::Config.load
+      server = Docyard::DevServer.new(
         port: options[:port],
         host: options[:host],
+        docs_path: config.source,
         search: options[:search]
       )
       server.start
+    rescue ConfigError => e
+      Docyard.logger.error(e.message)
+      exit(1)
     end
   end
 end

data/lib/docyard/components/processors/callout_processor.rb

@@ -112,7 +112,7 @@ module Docyard
         end
 
         def render_callout_html(type, title, content_html, icon_name)
-          icon_svg = Icons.render(icon_name, "duotone") || ""
+          icon_svg = Icons.render(icon_name, "regular") || ""
           renderer = Renderer.new
 
           renderer.render_partial(

data/lib/docyard/components/processors/code_block_extended_fence_postprocessor.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      # Restores placeholders after all code block processing.
+      # Runs after CodeBlockProcessor to ensure the HTML is fully rendered.
+      class CodeBlockExtendedFencePostprocessor < BaseProcessor
+        self.priority = 25
+
+        BACKTICK_PLACEHOLDER = "\u200B\u200B\u200B"
+        CODE_MARKER_PLACEHOLDER = "\u200B!\u200Bcode"
+
+        def postprocess(html)
+          html
+            .gsub(BACKTICK_PLACEHOLDER, "`")
+            .gsub(CODE_MARKER_PLACEHOLDER, "[!code")
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_block_extended_fence_preprocessor.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      # Handles 4+ backtick code fences (extended fences) for showing raw syntax.
+      # Escapes special markers so they display as raw text instead of being processed.
+      # Example: ```` (4 backticks) wrapping ```js shows the raw markdown syntax.
+      class CodeBlockExtendedFencePreprocessor < BaseProcessor
+        self.priority = 1
+
+        # Match 4+ backticks, capture language, content, and closing backticks
+        EXTENDED_FENCE_REGEX = /^(`{4,})(\w*)[^\n]*\n(.*?)^\1/m
+
+        # Placeholders using zero-width spaces
+        BACKTICK_PLACEHOLDER = "\u200B\u200B\u200B"
+        CODE_MARKER_PLACEHOLDER = "\u200B!\u200Bcode"
+
+        def preprocess(content)
+          content.gsub(EXTENDED_FENCE_REGEX) { |_| process_extended_fence(Regexp.last_match) }
+        end
+
+        private
+
+        def process_extended_fence(match)
+          lang = match[2]
+          code = match[3].chomp
+
+          # Replace backticks and code markers with placeholders
+          # This prevents other preprocessors from matching/processing them
+          escaped_code = code
+            .gsub("`", BACKTICK_PLACEHOLDER)
+            .gsub("[!code", CODE_MARKER_PLACEHOLDER)
+
+          # Output as regular 3-backtick fence so it goes through normal processing
+          lang_spec = lang.empty? ? "text" : lang
+          "```#{lang_spec}\n#{escaped_code}\n```"
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/processors/code_block_options_preprocessor.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../base_processor"
+require_relative "../../rendering/icons"
 
 module Docyard
   module Components
@@ -11,6 +12,7 @@ module Docyard
         CODE_FENCE_REGEX = /^```(\w+)(?:\s*\[([^\]]+)\])?(:\S+)?(?:\s*\{([^}\n]+)\})?/
         TABS_BLOCK_REGEX = /^:::[ \t]*tabs[ \t]*\n.*?^:::[ \t]*$/m
         CODE_GROUP_BLOCK_REGEX = /^:::[ \t]*code-group[ \t]*\n.*?^:::[ \t]*$/m
+        EXCLUDED_LANGUAGES = %w[filetree].freeze
 
         def preprocess(content)
           context[:code_block_options] ||= []
@@ -40,8 +42,16 @@ module Docyard
           position = match.begin(0)
           return match[0] if inside_special_block?(position)
 
+          original_lang = match[1]
+          return match[0] if excluded_language?(original_lang)
+
           store_code_block_options(match)
-          "```#{match[1]}"
+          highlight_lang = Icons.highlight_language(original_lang)
+          "```#{highlight_lang}"
+        end
+
+        def excluded_language?(lang)
+          EXCLUDED_LANGUAGES.include?(lang&.downcase)
         end
 
         def inside_special_block?(position)

data/lib/docyard/components/processors/code_block_processor.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "../../rendering/icons"
-require_relative "../../rendering/language_mapping"
 require_relative "../../rendering/renderer"
 require_relative "../base_processor"
 require_relative "../support/code_block/icon_detector"
 require_relative "../support/code_block/line_wrapper"
+require_relative "../support/code_block/line_number_resolver"
 require_relative "../support/tabs/range_finder"
 
 module Docyard
@@ -18,6 +18,7 @@ module Docyard
         self.priority = 20
 
         CodeBlockIconDetector = Support::CodeBlock::IconDetector
+        LineNumbers = Support::CodeBlock::LineNumberResolver
         TabsRangeFinder = Support::Tabs::RangeFinder
 
         def postprocess(html)
@@ -36,7 +37,6 @@ module Docyard
           @focus_lines = context[:code_block_focus_lines] || []
           @error_lines = context[:code_block_error_lines] || []
           @warning_lines = context[:code_block_warning_lines] || []
-          @global_line_numbers = context.dig(:config, "markdown", "lineNumbers") || false
           @tabs_ranges = TabsRangeFinder.find_ranges(html)
         end
 
@@ -80,8 +80,8 @@ module Docyard
         def extract_block_data(inner_html)
           opts = current_block_options
           code_text = extract_code_text(inner_html)
-          start_line = extract_start_line(opts[:option])
-          show_line_numbers = determine_line_numbers(opts[:option])
+          start_line = LineNumbers.start_line(opts[:option])
+          show_line_numbers = LineNumbers.enabled?(opts[:option])
           title_data = CodeBlockIconDetector.detect(opts[:title], opts[:lang])
 
           build_block_data(code_text, opts, show_line_numbers, start_line, title_data)
@@ -106,7 +106,7 @@ module Docyard
             error_lines: @error_lines[@block_index] || {},
             warning_lines: @warning_lines[@block_index] || {},
             show_line_numbers: show_line_numbers,
-            line_numbers: show_line_numbers ? generate_line_numbers(code_text, start_line) : [],
+            line_numbers: show_line_numbers ? LineNumbers.generate_numbers(code_text, start_line) : [],
             start_line: start_line,
             title: title_data[:title],
             icon: title_data[:icon],
@@ -123,25 +123,6 @@ module Docyard
           wrap_code_block(original_html, block_data)
         end
 
-        def determine_line_numbers(block_option)
-          return false if block_option == ":no-line-numbers"
-          return true if block_option&.start_with?(":line-numbers")
-
-          @global_line_numbers
-        end
-
-        def extract_start_line(block_option)
-          return 1 unless block_option&.include?("=")
-
-          block_option.split("=").last.to_i
-        end
-
-        def generate_line_numbers(code_text, start_line)
-          line_count = code_text.lines.count
-          line_count = 1 if line_count.zero?
-          (start_line...(start_line + line_count)).to_a
-        end
-
         def inside_tabs?(position)
           @tabs_ranges.any? { |range| range.cover?(position) }
         end

data/lib/docyard/components/processors/code_group_processor.rb

@@ -3,6 +3,7 @@
 require_relative "../base_processor"
 require_relative "../support/code_block/feature_extractor"
 require_relative "../support/code_block/line_wrapper"
+require_relative "../support/code_block/line_number_resolver"
 require_relative "../support/code_group/html_builder"
 require_relative "../support/markdown_code_block_helper"
 require_relative "../../rendering/icons"
@@ -26,6 +27,7 @@ module Docyard
 
         CodeBlockFeatureExtractor = Support::CodeBlock::FeatureExtractor
         CodeBlockLineWrapper = Support::CodeBlock::LineWrapper
+        LineNumbers = Support::CodeBlock::LineNumberResolver
         CodeGroupHtmlBuilder = Support::CodeGroup::HtmlBuilder
 
         def preprocess(content)
@@ -136,7 +138,7 @@ module Docyard
             focus_lines: block_data[:focus_lines] || {},
             error_lines: block_data[:error_lines] || {},
             warning_lines: block_data[:warning_lines] || {},
-            start_line: extract_start_line(block_data[:option])
+            start_line: LineNumbers.start_line(block_data[:option])
           }
         end
 
@@ -145,13 +147,13 @@ module Docyard
         end
 
         def base_locals(processed_html, code_text, block_data)
-          show_ln = line_numbers_enabled?(block_data[:option])
-          start = extract_start_line(block_data[:option])
+          show_ln = LineNumbers.enabled?(block_data[:option])
+          start = LineNumbers.start_line(block_data[:option])
 
           {
             code_block_html: processed_html, code_text: escape_html_attribute(code_text),
             copy_icon: Icons.render("copy", "regular") || "", show_line_numbers: show_ln,
-            line_numbers: show_ln ? generate_line_numbers(code_text, start) : [], start_line: start
+            line_numbers: show_ln ? LineNumbers.generate_numbers(code_text, start) : [], start_line: start
           }
         end
 
@@ -167,24 +169,6 @@ module Docyard
           { title: nil, icon: nil, icon_source: nil }
         end
 
-        def line_numbers_enabled?(option)
-          return false if option == ":no-line-numbers"
-          return true if option&.start_with?(":line-numbers")
-
-          false
-        end
-
-        def extract_start_line(option)
-          return 1 unless option&.include?("=")
-
-          option.split("=").last.to_i
-        end
-
-        def generate_line_numbers(code_text, start_line)
-          count = [code_text.lines.count, 1].max
-          (start_line...(start_line + count)).to_a
-        end
-
         def extract_code_text(html)
           CGI.unescapeHTML(html.gsub(/<[^>]+>/, "")).strip
         end

data/lib/docyard/components/processors/code_snippet_import_preprocessor.rb

@@ -124,6 +124,7 @@ module Docyard
         end
 
         def import_error(filepath, message)
+          Docyard.logger.warn("Code snippet import failed: #{filepath} - #{message}")
           "```\nError importing #{filepath}: #{message}\n```"
         end
       end

data/lib/docyard/components/processors/file_tree_processor.rb

@@ -2,7 +2,6 @@
 
 require_relative "../base_processor"
 require_relative "../support/markdown_code_block_helper"
-require_relative "../../rendering/icons"
 
 module Docyard
   module Components
@@ -135,7 +134,7 @@ module Docyard
 
         def icon_for(type)
           icon_name = type == :folder ? "folder-open" : "file-text"
-          Icons.render(icon_name)
+          %(<i class="ph ph-#{icon_name}" aria-hidden="true"></i>)
         end
 
         def escape_html(text)

data/lib/docyard/components/processors/icon_processor.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../../rendering/icons"
 require_relative "../base_processor"
 
 module Docyard
@@ -10,6 +9,7 @@ module Docyard
         self.priority = 20
 
         ICON_PATTERN = /:([a-z][a-z0-9-]*):(?:([a-z]+):)?/i
+        VALID_WEIGHTS = %w[regular bold fill light thin duotone].freeze
 
         def postprocess(html)
           segments = split_preserving_code_blocks(html)
@@ -44,9 +44,15 @@ module Docyard
           content.gsub(ICON_PATTERN) do
             icon_name = Regexp.last_match(1)
             weight = Regexp.last_match(2) || "regular"
-            Icons.render(icon_name, weight) || Regexp.last_match(0)
+            render_icon(icon_name, weight)
           end
         end
+
+        def render_icon(name, weight)
+          weight = "regular" unless VALID_WEIGHTS.include?(weight)
+          weight_class = weight == "regular" ? "ph" : "ph-#{weight}"
+          %(<i class="#{weight_class} ph-#{name}" aria-hidden="true"></i>)
+        end
       end
     end
   end