docyard 0.2.0 → 0.4.0

data/lib/docyard/build/static_generator.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "tty-progressbar"
+
+module Docyard
+  module Build
+    class StaticGenerator
+      attr_reader :config, :verbose, :renderer
+
+      def initialize(config, verbose: false)
+        @config = config
+        @verbose = verbose
+        @renderer = Renderer.new(base_url: config.build.base_url)
+      end
+
+      def generate
+        markdown_files = collect_markdown_files
+        puts "\n[✓] Found #{markdown_files.size} markdown files"
+
+        progress = TTY::ProgressBar.new(
+          "Generating pages [:bar] :current/:total (:percent%)",
+          total: markdown_files.size,
+          width: 50
+        )
+
+        markdown_files.each do |file_path|
+          generate_page(file_path)
+          progress.advance
+        end
+
+        markdown_files.size
+      end
+
+      private
+
+      def collect_markdown_files
+        Dir.glob(File.join("docs", "**", "*.md"))
+      end
+
+      def generate_page(markdown_file_path)
+        output_path = determine_output_path(markdown_file_path)
+        current_path = determine_current_path(markdown_file_path)
+
+        sidebar_html = build_sidebar(current_path)
+        html_content = renderer.render_file(
+          markdown_file_path,
+          sidebar_html: sidebar_html,
+          branding: branding_options
+        )
+
+        FileUtils.mkdir_p(File.dirname(output_path))
+        File.write(output_path, html_content)
+
+        log "Generated: #{output_path}" if verbose
+      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_dir
+
+        if base_name == "index"
+          File.join(output_dir, dir_name, "index.html")
+        else
+          File.join(output_dir, dir_name, base_name, "index.html")
+        end
+      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
+      end
+
+      def build_sidebar(current_path)
+        SidebarBuilder.new(
+          docs_path: "docs",
+          current_path: current_path,
+          config: config
+        ).to_html
+      end
+
+      def branding_options
+        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
+      end
+
+      def log(message)
+        puts message if verbose
+      end
+    end
+  end
+end

data/lib/docyard/builder.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tty-progressbar"
+
+module Docyard
+  class Builder
+    attr_reader :config, :clean, :verbose, :start_time
+
+    def initialize(clean: true, verbose: false)
+      @config = Config.new
+      @clean = clean
+      @verbose = verbose
+      @start_time = Time.now
+    end
+
+    def build
+      prepare_output_directory
+      log "Building static site..."
+
+      pages_built = generate_static_pages
+      bundles_created = bundle_assets
+      assets_copied = copy_static_files
+      generate_seo_files
+
+      display_summary(pages_built, bundles_created, assets_copied)
+      true
+    rescue StandardError => e
+      error "Build failed: #{e.message}"
+      error e.backtrace.first if verbose
+      false
+    end
+
+    private
+
+    def prepare_output_directory
+      output_dir = config.build.output_dir
+
+      if clean && Dir.exist?(output_dir)
+        log "[✓] Cleaning #{output_dir}/ directory"
+        FileUtils.rm_rf(output_dir)
+      end
+
+      FileUtils.mkdir_p(output_dir)
+    end
+
+    def generate_static_pages
+      require_relative "build/static_generator"
+      generator = Build::StaticGenerator.new(config, verbose: verbose)
+      generator.generate
+    end
+
+    def bundle_assets
+      require_relative "build/asset_bundler"
+      bundler = Build::AssetBundler.new(config, verbose: verbose)
+      bundler.bundle
+    end
+
+    def copy_static_files
+      require_relative "build/file_copier"
+      copier = Build::FileCopier.new(config, verbose: verbose)
+      copier.copy
+    end
+
+    def generate_seo_files
+      require_relative "build/sitemap_generator"
+      sitemap_gen = Build::SitemapGenerator.new(config)
+      sitemap_gen.generate
+
+      File.write(File.join(config.build.output_dir, "robots.txt"), robots_txt_content)
+      log "[✓] Generated robots.txt"
+    end
+
+    def robots_txt_content
+      base_url = config.build.base_url
+      base_url = "#{base_url}/" unless base_url.end_with?("/")
+
+      <<~ROBOTS
+        User-agent: *
+        Allow: /
+
+        Sitemap: #{base_url}sitemap.xml
+      ROBOTS
+    end
+
+    def display_summary(pages, bundles, assets)
+      elapsed = Time.now - start_time
+
+      puts "\n#{'=' * 50}"
+      puts "Build complete in #{format('%.2f', elapsed)}s"
+      puts "Output: #{config.build.output_dir}/"
+      puts "#{pages} pages, #{bundles} bundles, #{assets} static files"
+      puts "=" * 50
+    end
+
+    def log(message)
+      puts message
+    end
+
+    def error(message)
+      warn "[ERROR] #{message}"
+    end
+  end
+end

data/lib/docyard/cli.rb

@@ -19,6 +19,25 @@ module Docyard
       exit(1) unless initializer.run
     end
 
+    desc "build", "Build static site for production"
+    method_option :clean, type: :boolean, default: true, desc: "Clean output directory before building"
+    method_option :verbose, type: :boolean, default: false, aliases: "-v", desc: "Show verbose output"
+    def build
+      require_relative "builder"
+      builder = Docyard::Builder.new(
+        clean: options[:clean],
+        verbose: options[:verbose]
+      )
+      exit(1) unless builder.build
+    end
+
+    desc "preview", "Preview the built site locally"
+    method_option :port, type: :numeric, default: 4000, aliases: "-p", desc: "Port to run preview server on"
+    def preview
+      require_relative "preview_server"
+      Docyard::PreviewServer.new(port: options[:port]).start
+    end
+
     desc "serve", "Start the development server"
     method_option :port, type: :numeric, default: 4200, aliases: "-p", desc: "Port to run the server on"
     method_option :host, type: :string, default: "localhost", aliases: "-h", desc: "Host to bind the server to"

data/lib/docyard/components/base_processor.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    class BaseProcessor
+      class << self
+        attr_accessor :priority
+
+        def inherited(subclass)
+          super
+          Registry.register(subclass)
+        end
+      end
+
+      def preprocess(content)
+        content
+      end
+
+      def postprocess(html)
+        html
+      end
+    end
+  end
+end

data/lib/docyard/components/callout_processor.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "../icons"
+require_relative "../renderer"
+require_relative "base_processor"
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Docyard
+  module Components
+    class CalloutProcessor < BaseProcessor
+      self.priority = 10
+
+      CALLOUT_TYPES = {
+        "note" => { title: "Note", icon: "info", color: "note" },
+        "tip" => { title: "Tip", icon: "lightbulb", color: "tip" },
+        "important" => { title: "Important", icon: "warning-circle", color: "important" },
+        "warning" => { title: "Warning", icon: "warning", color: "warning" },
+        "danger" => { title: "Danger", icon: "siren", color: "danger" }
+      }.freeze
+
+      GITHUB_ALERT_TYPES = {
+        "NOTE" => "note",
+        "TIP" => "tip",
+        "IMPORTANT" => "important",
+        "WARNING" => "warning",
+        "CAUTION" => "danger"
+      }.freeze
+
+      def preprocess(markdown)
+        process_container_syntax(markdown)
+      end
+
+      def postprocess(html)
+        process_github_alerts(html)
+      end
+
+      private
+
+      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))
+        end
+      end
+
+      def process_callout_match(original_match, type_raw, custom_title, content_markdown)
+        type = type_raw.downcase
+        return original_match unless CALLOUT_TYPES.key?(type)
+
+        config = CALLOUT_TYPES[type]
+        title = determine_title(custom_title, config[:title])
+        content_html = render_markdown_content(content_markdown.strip)
+
+        wrap_in_nomarkdown(render_callout_html(type, title, content_html, config[:icon]))
+      end
+
+      def determine_title(custom_title, default_title)
+        title = custom_title&.strip
+        title.nil? || title.empty? ? default_title : title
+      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 process_github_alerts(html)
+        github_alert_regex = %r{
+          <blockquote>\s*
+          <p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*
+          (?:<br\s*/>)?\s*
+          (.*?)</p>
+          (.*?)
+          </blockquote>
+        }mx
+
+        html.gsub(github_alert_regex) do
+          process_github_alert_match(Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3))
+        end
+      end
+
+      def process_github_alert_match(alert_type, first_para, rest_content)
+        type = GITHUB_ALERT_TYPES[alert_type]
+        config = CALLOUT_TYPES[type]
+        content_html = combine_alert_content(first_para.strip, rest_content.strip)
+
+        render_callout_html(type, config[:title], content_html, config[:icon])
+      end
+
+      def combine_alert_content(first_para, rest_content)
+        return "<p>#{first_para}</p>" if rest_content.empty?
+
+        "<p>#{first_para}</p>#{rest_content}"
+      end
+
+      def render_callout_html(type, title, content_html, icon_name)
+        icon_svg = Icons.render(icon_name, "duotone") || ""
+        renderer = Renderer.new
+
+        renderer.render_partial(
+          "_callout", {
+            type: type,
+            title: title,
+            content_html: content_html,
+            icon_svg: icon_svg
+          }
+        )
+      end
+    end
+  end
+end

data/lib/docyard/components/code_block_processor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../icons"
+require_relative "../renderer"
+require_relative "base_processor"
+
+module Docyard
+  module Components
+    class CodeBlockProcessor < BaseProcessor
+      self.priority = 20
+
+      def postprocess(html)
+        return html unless html.include?('<div class="highlight">')
+
+        html.gsub(%r{<div class="highlight">(.*?)</div>}m) do
+          process_code_block(Regexp.last_match(0), Regexp.last_match(1))
+        end
+      end
+
+      private
+
+      def process_code_block(original_html, inner_html)
+        code_text = extract_code_text(inner_html)
+
+        render_code_block_with_copy(original_html, code_text)
+      end
+
+      def extract_code_text(html)
+        text = html.gsub(/<[^>]+>/, "")
+        text = CGI.unescapeHTML(text)
+        text.strip
+      end
+
+      def render_code_block_with_copy(code_block_html, code_text)
+        copy_icon = Icons.render("copy", "regular") || ""
+        renderer = Renderer.new
+
+        renderer.render_partial(
+          "_code_block", {
+            code_block_html: code_block_html,
+            code_text: escape_html_attribute(code_text),
+            copy_icon: copy_icon
+          }
+        )
+      end
+
+      def escape_html_attribute(text)
+        text.gsub('"', "&quot;")
+          .gsub("'", "&#39;")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+      end
+    end
+  end
+end

data/lib/docyard/components/code_detector.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../language_mapping"
+
+module Docyard
+  module Components
+    class CodeDetector
+      def self.detect(content)
+        new(content).detect
+      end
+
+      def initialize(content)
+        @content = content
+      end
+
+      def detect
+        return nil unless code_only?
+
+        language = extract_language
+        return nil unless language
+
+        icon_for_language(language)
+      end
+
+      private
+
+      attr_reader :content
+
+      def code_only?
+        stripped = content.strip
+        return false unless stripped.start_with?("```") && stripped.end_with?("```")
+
+        parts = stripped.split("```")
+        parts.length == 2 && parts[0].empty?
+      end
+
+      def extract_language
+        parts = content.strip.split("```")
+        return nil unless parts[1]
+
+        lines = parts[1].split("\n", 2)
+        lang_line = lines[0].strip
+        return nil if lang_line.empty? || lang_line.include?(" ")
+
+        lang_line.downcase
+      end
+
+      def icon_for_language(language)
+        if LanguageMapping.terminal_language?(language)
+          { icon: "terminal-window", source: "phosphor" }
+        elsif (extension = LanguageMapping.extension_for(language))
+          { icon: extension, source: "file-extension" }
+        else
+          { icon: "file", source: "phosphor" }
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/icon_detector.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "code_detector"
+
+module Docyard
+  module Components
+    class IconDetector
+      MANUAL_ICON_PATTERN = /^:([a-z0-9-]+):\s*(.+)$/i
+
+      def self.detect(tab_name, tab_content)
+        new(tab_name, tab_content).detect
+      end
+
+      def initialize(tab_name, tab_content)
+        @tab_name = tab_name
+        @tab_content = tab_content
+      end
+
+      def detect
+        manual_icon || auto_detected_icon || no_icon
+      end
+
+      private
+
+      attr_reader :tab_name, :tab_content
+
+      def manual_icon
+        return nil unless tab_name.match(MANUAL_ICON_PATTERN)
+
+        {
+          name: Regexp.last_match(2).strip,
+          icon: Regexp.last_match(1),
+          icon_source: "phosphor"
+        }
+      end
+
+      def auto_detected_icon
+        detected = CodeDetector.detect(tab_content)
+        return nil unless detected
+
+        {
+          name: tab_name,
+          icon: detected[:icon],
+          icon_source: detected[:source]
+        }
+      end
+
+      def no_icon
+        {
+          name: tab_name,
+          icon: nil,
+          icon_source: nil
+        }
+      end
+    end
+  end
+end

data/lib/docyard/components/icon_processor.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../icons"
+require_relative "base_processor"
+
+module Docyard
+  module Components
+    class IconProcessor < BaseProcessor
+      self.priority = 20
+
+      ICON_PATTERN = /:([a-z][a-z0-9-]*):(?:([a-z]+):)?/i
+
+      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(ICON_PATTERN) do
+          icon_name = Regexp.last_match(1)
+          weight = Regexp.last_match(2) || "regular"
+          Icons.render(icon_name, weight) || Regexp.last_match(0)
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/registry.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    class Registry
+      @processors = []
+
+      class << self
+        def register(processor_class)
+          @processors << processor_class
+          @processors.sort_by! { |p| p.priority || 100 }
+        end
+
+        def run_preprocessors(content)
+          @processors.reduce(content) do |processed_content, processor_class|
+            processor_class.new.preprocess(processed_content)
+          end
+        end
+
+        def run_postprocessors(html)
+          @processors.reduce(html) do |processed_html, processor_class|
+            processor_class.new.postprocess(processed_html)
+          end
+        end
+
+        def reset!
+          @processors = []
+        end
+
+        attr_reader :processors
+      end
+    end
+  end
+end

data/lib/docyard/components/table_wrapper_processor.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    class TableWrapperProcessor < BaseProcessor
+      self.priority = 100
+
+      def postprocess(html)
+        wrapped = html.gsub(/<table([^>]*)>/) do
+          attributes = Regexp.last_match(1)
+          "<div class=\"table-wrapper\"><table#{attributes}>"
+        end
+
+        wrapped.gsub("</table>", "</table></div>")
+      end
+    end
+  end
+end