docyard 0.8.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/aliases.rb

@@ -2,17 +2,29 @@
 
 module Docyard
   module Components
+    AbbreviationProcessor = Processors::AbbreviationProcessor
+    AccordionProcessor = Processors::AccordionProcessor
+    BadgeProcessor = Processors::BadgeProcessor
+    StepsProcessor = Processors::StepsProcessor
+    CardsProcessor = Processors::CardsProcessor
     CalloutProcessor = Processors::CalloutProcessor
     CodeBlockProcessor = Processors::CodeBlockProcessor
+    CodeGroupProcessor = Processors::CodeGroupProcessor
     CodeBlockDiffPreprocessor = Processors::CodeBlockDiffPreprocessor
     CodeBlockFocusPreprocessor = Processors::CodeBlockFocusPreprocessor
     CodeBlockOptionsPreprocessor = Processors::CodeBlockOptionsPreprocessor
     CodeSnippetImportPreprocessor = Processors::CodeSnippetImportPreprocessor
+    CustomAnchorProcessor = Processors::CustomAnchorProcessor
+    ImageCaptionProcessor = Processors::ImageCaptionProcessor
+    IncludeProcessor = Processors::IncludeProcessor
+    VideoEmbedProcessor = Processors::VideoEmbedProcessor
+    FileTreeProcessor = Processors::FileTreeProcessor
     HeadingAnchorProcessor = Processors::HeadingAnchorProcessor
     IconProcessor = Processors::IconProcessor
     TableOfContentsProcessor = Processors::TableOfContentsProcessor
     TableWrapperProcessor = Processors::TableWrapperProcessor
     TabsProcessor = Processors::TabsProcessor
+    TooltipProcessor = Processors::TooltipProcessor
 
     CodeDetector = Support::CodeDetector
     IconDetector = Support::Tabs::IconDetector

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+
+module Docyard
+  module Components
+    module Processors
+      class AbbreviationProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        DEFINITION_PATTERN = /^\*\[([^\]]+)\]:\s*(.+)$/
+        self.priority = 5
+
+        def preprocess(content)
+          abbreviations = extract_abbreviations_outside_code_blocks(content)
+          return content if abbreviations.empty?
+
+          process_outside_code_blocks(content) do |segment|
+            segment = remove_definitions(segment)
+            apply_abbreviations(segment, abbreviations)
+          end
+        end
+
+        private
+
+        def extract_abbreviations_outside_code_blocks(content)
+          abbreviations = {}
+          process_outside_code_blocks(content) do |segment|
+            segment.scan(DEFINITION_PATTERN) do |term, definition|
+              abbreviations[term] = definition.strip
+            end
+            segment
+          end
+          abbreviations
+        end
+
+        def remove_definitions(content)
+          content.gsub(/^[ \t]*\*\[([^\]]+)\]:\s*.+$\n?/, "")
+        end
+
+        def apply_abbreviations(content, abbreviations)
+          abbreviations.each do |term, definition|
+            pattern = build_term_pattern(term)
+            content = content.gsub(pattern) do |match|
+              build_abbr_tag(match, definition)
+            end
+          end
+          content
+        end
+
+        def build_term_pattern(term)
+          escaped = Regexp.escape(term)
+          /(?<![<\w])#{escaped}(?![>\w])/
+        end
+
+        def build_abbr_tag(term, definition)
+          escaped_definition = escape_html(definition)
+          %(<abbr class="docyard-abbr" data-definition="#{escaped_definition}">#{term}</abbr>)
+        end
+
+        def escape_html(text)
+          text.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub('"', "&quot;")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../../rendering/icons"
+require_relative "../../rendering/renderer"
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Docyard
+  module Components
+    module Processors
+      class AccordionProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        self.priority = 10
+
+        DETAILS_PATTERN = /^:::details(?:\{([^}]*)\})?\s*\n(.*?)^:::\s*$/m
+
+        def preprocess(markdown)
+          @code_block_ranges = find_code_block_ranges(markdown)
+
+          markdown.gsub(DETAILS_PATTERN) do
+            match = Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            attributes = parse_attributes(match[1])
+            content_markdown = match[2]
+
+            title = attributes["title"] || "Details"
+            open = attributes.key?("open")
+            content_html = render_markdown_content(content_markdown.strip)
+
+            wrap_in_nomarkdown(render_accordion_html(title, content_html, open))
+          end
+        end
+
+        private
+
+        def parse_attributes(attr_string)
+          return {} if attr_string.nil? || attr_string.empty?
+
+          attrs = {}
+          attr_string.scan(/(\w+)(?:="([^"]*)")?/) do |key, value|
+            attrs[key] = value || true
+          end
+          attrs
+        end
+
+        def render_markdown_content(content_markdown)
+          return "" if content_markdown.empty?
+
+          Kramdown::Document.new(
+            content_markdown,
+            input: "GFM",
+            hard_wrap: false,
+            syntax_highlighter: "rouge"
+          ).to_html
+        end
+
+        def wrap_in_nomarkdown(html)
+          "{::nomarkdown}\n#{html}\n{:/nomarkdown}"
+        end
+
+        def render_accordion_html(title, content_html, open)
+          icon_svg = Icons.render("caret-right") || ""
+          renderer = Renderer.new
+
+          renderer.render_partial(
+            "_accordion", {
+              title: title,
+              content_html: content_html,
+              icon_svg: icon_svg,
+              open: open
+            }
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+
+module Docyard
+  module Components
+    module Processors
+      class BadgeProcessor < BaseProcessor
+        self.priority = 15
+
+        BADGE_PATTERN = /:badge\[([^\]]*)\](?:\{([^}]*)\})?/
+
+        VALID_TYPES = %w[default success warning danger].freeze
+
+        def postprocess(html)
+          segments = split_preserving_code_blocks(html)
+
+          segments.map do |segment|
+            segment[:type] == :code ? segment[:content] : process_segment(segment[:content])
+          end.join
+        end
+
+        private
+
+        def split_preserving_code_blocks(html)
+          segments = []
+          current_pos = 0
+
+          html.scan(%r{<(code|pre)[^>]*>.*?</\1>}m) do
+            match_start = Regexp.last_match.begin(0)
+            match_end = Regexp.last_match.end(0)
+
+            segments << { type: :text, content: html[current_pos...match_start] } if match_start > current_pos
+            segments << { type: :code, content: html[match_start...match_end] }
+
+            current_pos = match_end
+          end
+
+          segments << { type: :text, content: html[current_pos..] } if current_pos < html.length
+
+          segments.empty? ? [{ type: :text, content: html }] : segments
+        end
+
+        def process_segment(content)
+          content.gsub(BADGE_PATTERN) do
+            text = Regexp.last_match(1)
+            attrs = Regexp.last_match(2)
+
+            render_badge(text, parse_attributes(attrs))
+          end
+        end
+
+        def parse_attributes(attrs_string)
+          return {} if attrs_string.nil? || attrs_string.empty?
+
+          attrs = {}
+          attrs_string.scan(/(\w+)=["'\u201C\u201D]([^"'\u201C\u201D]*)["'\u201C\u201D]/) do |key, value|
+            attrs[key] = value
+          end
+          attrs
+        end
+
+        def render_badge(text, attrs)
+          type = attrs["type"] || "default"
+          type = "default" unless VALID_TYPES.include?(type)
+
+          %(<span class="docyard-badge docyard-badge--#{type}">#{text}</span>)
+        end
+      end
+    end
+  end
+end

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

@@ -3,6 +3,7 @@
 require_relative "../../rendering/icons"
 require_relative "../../rendering/renderer"
 require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
 require "kramdown"
 require "kramdown-parser-gfm"
 
@@ -10,6 +11,8 @@ module Docyard
   module Components
     module Processors
       class CalloutProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
         self.priority = 10
 
         CALLOUT_TYPES = {
@@ -29,6 +32,7 @@ module Docyard
         }.freeze
 
         def preprocess(markdown)
+          @code_block_ranges = find_code_block_ranges(markdown)
           process_container_syntax(markdown)
         end
 
@@ -40,8 +44,10 @@ module Docyard
 
         def process_container_syntax(markdown)
           markdown.gsub(/^:::[ \t]*(\w+)(?:[ \t]+([^\n]+?))?[ \t]*\n(.*?)^:::[ \t]*$/m) do
-            process_callout_match(Regexp.last_match(0), Regexp.last_match(1), Regexp.last_match(2),
-                                  Regexp.last_match(3))
+            match = Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            process_callout_match(match[0], match[1], match[2], match[3])
           end
         end
 
@@ -106,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(