docyard 0.6.0 → 0.8.0

data/lib/docyard/rendering/renderer.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "erb"
+require_relative "../config/constants"
+require_relative "icon_helpers"
+
+module Docyard
+  class Renderer
+    include Utils::UrlHelpers
+    include IconHelpers
+
+    LAYOUTS_PATH = File.join(__dir__, "../templates", "layouts")
+    ERRORS_PATH = File.join(__dir__, "../templates", "errors")
+    PARTIALS_PATH = File.join(__dir__, "../templates", "partials")
+    DEFAULT_LAYOUT = "default"
+
+    attr_reader :base_url, :config
+
+    def initialize(base_url: "/", config: nil)
+      @base_url = normalize_base_url(base_url)
+      @config = config
+    end
+
+    def render_file(file_path, sidebar_html: "", prev_next_html: "", breadcrumbs: nil, branding: {},
+                    template_options: {}, current_path: "/")
+      markdown = Markdown.new(File.read(file_path), config: config)
+
+      render(
+        content: strip_md_from_links(markdown.html),
+        page_title: markdown.title || Constants::DEFAULT_SITE_TITLE,
+        navigation: build_navigation(sidebar_html, prev_next_html, markdown.toc, breadcrumbs),
+        branding: branding,
+        template_options: template_options,
+        current_path: current_path
+      )
+    end
+
+    def build_navigation(sidebar_html, prev_next_html, toc, breadcrumbs)
+      { sidebar_html: sidebar_html, prev_next_html: prev_next_html, toc: toc, breadcrumbs: breadcrumbs }
+    end
+
+    def render(content:, page_title: Constants::DEFAULT_SITE_TITLE, navigation: {}, branding: {},
+               template_options: {}, current_path: "/")
+      layout = template_options[:template] || DEFAULT_LAYOUT
+      layout_path = File.join(LAYOUTS_PATH, "#{layout}.html.erb")
+      template = File.read(layout_path)
+
+      assign_content_variables(content, page_title, navigation)
+      assign_branding_variables(branding, current_path)
+      assign_template_variables(template_options)
+
+      ERB.new(template).result(binding)
+    end
+
+    def render_not_found
+      render_error_template(404)
+    end
+
+    def render_server_error(error)
+      @error_message = error.message
+      @backtrace = error.backtrace.join("\n")
+      render_error_template(500)
+    end
+
+    def render_error_template(status)
+      error_template_path = File.join(ERRORS_PATH, "#{status}.html.erb")
+      template = File.read(error_template_path)
+      ERB.new(template).result(binding)
+    end
+
+    def render_partial(name, locals = {})
+      partial_path = File.join(PARTIALS_PATH, "#{name}.html.erb")
+      template = File.read(partial_path)
+
+      locals.each { |key, value| instance_variable_set("@#{key}", value) }
+
+      ERB.new(template).result(binding)
+    end
+
+    def asset_path(path)
+      return path if path.nil? || path.start_with?("http://", "https://")
+
+      "#{base_url}#{path}"
+    end
+
+    private
+
+    def assign_content_variables(content, page_title, navigation)
+      @content = content
+      @page_title = page_title
+      @sidebar_html = navigation[:sidebar_html] || ""
+      @prev_next_html = navigation[:prev_next_html] || ""
+      @toc = navigation[:toc] || []
+      @breadcrumbs = navigation[:breadcrumbs]
+    end
+
+    def assign_branding_variables(branding, current_path = "/")
+      assign_site_branding(branding)
+      assign_search_options(branding)
+      assign_credits_and_social(branding)
+      assign_tabs(branding, current_path)
+    end
+
+    def assign_site_branding(branding)
+      @site_title = branding[:site_title] || Constants::DEFAULT_SITE_TITLE
+      @site_description = branding[:site_description] || ""
+      @logo = branding[:logo] || Constants::DEFAULT_LOGO_PATH
+      @logo_dark = branding[:logo_dark]
+      @favicon = branding[:favicon] || Constants::DEFAULT_FAVICON_PATH
+      @has_custom_logo = branding[:has_custom_logo] || false
+    end
+
+    def assign_search_options(branding)
+      @search_enabled = branding[:search_enabled].nil? || branding[:search_enabled]
+      @search_placeholder = branding[:search_placeholder] || "Search documentation..."
+    end
+
+    def assign_credits_and_social(branding)
+      @credits = branding[:credits] != false
+      @copyright = branding[:copyright]
+      @social = branding[:social] || []
+      @header_ctas = branding[:header_ctas] || []
+    end
+
+    def assign_tabs(branding, current_path)
+      tabs = branding[:tabs] || []
+      @tabs = tabs.map { |tab| tab.merge(active: tab_active?(tab[:href], current_path)) }
+      @has_tabs = branding[:has_tabs] || false
+      @current_path = current_path
+    end
+
+    def tab_active?(tab_href, current_path)
+      return false if tab_href.nil? || current_path.nil?
+      return false if tab_href.start_with?("http://", "https://")
+
+      normalized_tab = tab_href.chomp("/")
+      normalized_current = current_path.chomp("/")
+
+      return true if normalized_tab == normalized_current
+
+      current_path.start_with?("#{normalized_tab}/")
+    end
+
+    def assign_template_variables(template_options)
+      @hero = template_options[:hero]
+      @features = template_options[:features]
+      @features_header = template_options[:features_header]
+      @show_sidebar = template_options.fetch(:show_sidebar, true)
+      @show_toc = template_options.fetch(:show_toc, true)
+      assign_footer_from_landing(template_options[:footer])
+    end
+
+    def assign_footer_from_landing(footer)
+      return unless footer
+
+      @footer_links = footer[:links]
+    end
+
+    def strip_md_from_links(html)
+      html.gsub(/href="([^"]+)\.md"/, 'href="\1"')
+    end
+  end
+end

data/lib/docyard/rendering/template_resolver.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Docyard
+  class TemplateResolver
+    BACKGROUNDS = %w[grid glow mesh none].freeze
+    DEFAULT_BACKGROUND = "grid"
+
+    attr_reader :frontmatter, :site_config
+
+    def initialize(frontmatter, site_config = {})
+      @frontmatter = frontmatter || {}
+      @site_config = site_config || {}
+    end
+
+    def landing?
+      landing_config.any?
+    end
+
+    def template
+      landing? ? "splash" : "default"
+    end
+
+    def show_sidebar?
+      if landing?
+        landing_config.fetch("sidebar", false)
+      else
+        true
+      end
+    end
+
+    def show_toc?
+      return false if landing?
+
+      true
+    end
+
+    def hero_config
+      return nil unless landing?
+
+      hero = landing_config["hero"]
+      return nil unless hero.is_a?(Hash)
+
+      symbolize_hero(hero)
+    end
+
+    def features_config
+      return nil unless landing?
+
+      features = landing_config["features"]
+      return nil unless features.is_a?(Array)
+
+      features.map { |f| symbolize_feature(f) }
+    end
+
+    def features_header_config
+      return nil unless landing?
+
+      header = landing_config["features_header"]
+      return nil unless header.is_a?(Hash)
+
+      {
+        label: header["label"],
+        title: header["title"],
+        description: header["description"]
+      }.compact
+    end
+
+    def footer_config
+      return nil unless landing?
+
+      footer = landing_config["footer"]
+      return nil unless footer.is_a?(Hash)
+
+      {
+        links: normalize_footer_links(footer["links"])
+      }
+    end
+
+    def to_options
+      {
+        template: template,
+        landing: landing?,
+        show_sidebar: show_sidebar?,
+        show_toc: show_toc?,
+        hero: hero_config,
+        features: features_config,
+        features_header: features_header_config,
+        footer: footer_config
+      }
+    end
+
+    private
+
+    def normalize_footer_links(links)
+      return nil unless links.is_a?(Array)
+
+      links.map do |link|
+        next unless link.is_a?(Hash)
+
+        { text: link["text"], link: link["link"] }
+      end.compact
+    end
+
+    def landing_config
+      @landing_config ||= frontmatter["landing"] || site_config["landing"] || {}
+    end
+
+    def symbolize_hero(hero)
+      background = hero["background"]
+      validated_bg = BACKGROUNDS.include?(background) ? background : DEFAULT_BACKGROUND
+
+      {
+        background: validated_bg,
+        badge: hero["badge"],
+        name: hero["name"],
+        title: hero["title"],
+        tagline: hero["tagline"],
+        gradient: hero.fetch("gradient", true),
+        image: symbolize_image(hero["image"]),
+        actions: symbolize_actions(hero["actions"])
+      }.compact
+    end
+
+    def symbolize_image(image)
+      return nil unless image.is_a?(Hash)
+
+      if image["light"] || image["dark"]
+        {
+          light: image["light"],
+          dark: image["dark"],
+          alt: image["alt"]
+        }.compact
+      else
+        {
+          src: image["src"],
+          alt: image["alt"]
+        }.compact
+      end
+    end
+
+    def symbolize_actions(actions)
+      return nil unless actions.is_a?(Array)
+
+      actions.map do |action|
+        {
+          text: action["text"],
+          link: action["link"],
+          icon: action["icon"],
+          variant: action["variant"] || "primary",
+          target: action["target"],
+          rel: action["rel"]
+        }.compact
+      end
+    end
+
+    def symbolize_feature(feature)
+      return {} unless feature.is_a?(Hash)
+
+      {
+        title: feature["title"],
+        description: feature["description"],
+        icon: feature["icon"],
+        color: feature["color"],
+        link: feature["link"],
+        link_text: feature["link_text"],
+        size: feature["size"],
+        target: feature["target"],
+        rel: feature["rel"]
+      }.compact
+    end
+  end
+end

data/lib/docyard/routing/fallback_resolver.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Routing
+    class FallbackResolver
+      attr_reader :docs_path, :sidebar_builder
+
+      def initialize(docs_path:, sidebar_builder:)
+        @docs_path = docs_path
+        @sidebar_builder = sidebar_builder
+      end
+
+      def resolve_fallback(request_path)
+        return nil if file_exists?(request_path)
+
+        find_first_item_in_section(request_path)
+      end
+
+      private
+
+      def file_exists?(request_path)
+        clean_path = sanitize_path(request_path)
+
+        file_path = File.join(docs_path, "#{clean_path}.md")
+        return true if File.file?(file_path)
+
+        index_path = File.join(docs_path, clean_path, "index.md")
+        File.file?(index_path)
+      end
+
+      def sanitize_path(request_path)
+        clean = request_path.to_s.delete_prefix("/").delete_suffix("/")
+        clean = "index" if clean.empty?
+        clean.delete_suffix(".md")
+      end
+
+      def find_first_item_in_section(request_path)
+        tree = sidebar_builder.tree
+
+        if root_path?(request_path)
+          find_first_navigable_item(tree)
+        else
+          section = find_section_in_tree(tree, request_path)
+          section ? find_first_navigable_item(section[:children] || []) : nil
+        end
+      end
+
+      def root_path?(request_path)
+        request_path.nil? || request_path == "/" || request_path.empty?
+      end
+
+      def find_section_in_tree(tree, path)
+        normalized_path = normalize_path(path)
+
+        tree.each do |item|
+          return item if path_matches_section?(item, normalized_path)
+
+          if item[:children]&.any?
+            found = find_section_in_tree(item[:children], path)
+            return found if found
+          end
+        end
+
+        nil
+      end
+
+      def normalize_path(path)
+        path.to_s.delete_prefix("/").delete_suffix("/").downcase
+      end
+
+      def path_matches_section?(item, normalized_path)
+        return false unless item[:type] == :directory
+
+        item_path = item[:title].to_s.downcase.gsub(/\s+/, "-")
+        item_path == normalized_path
+      end
+
+      def find_first_navigable_item(items)
+        items.each do |item|
+          return item[:path] if item[:path] && item[:type] == :file
+
+          if item[:children]&.any?
+            found = find_first_navigable_item(item[:children])
+            return found if found
+          end
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/docyard/search/build_indexer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Docyard
+  module Search
+    class BuildIndexer
+      include PagefindSupport
+
+      PAGEFIND_COMMAND = "npx"
+
+      attr_reader :config, :output_dir, :verbose
+
+      def initialize(config, verbose: false)
+        @config = config
+        @output_dir = config.build.output
+        @verbose = verbose
+      end
+
+      def index
+        return 0 unless search_enabled?
+
+        log "Generating search index..."
+
+        unless pagefind_available?
+          warn_pagefind_missing
+          return 0
+        end
+
+        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
+        else
+          log_warning "[!] Search indexing failed: #{stderr}"
+          0
+        end
+      end
+
+      def extract_page_count(output)
+        if output =~ /Indexed (\d+) page/i
+          Regexp.last_match(1).to_i
+        else
+          0
+        end
+      end
+
+      def log(message)
+        puts message
+      end
+
+      def log_warning(message)
+        warn message
+      end
+    end
+  end
+end

data/lib/docyard/search/dev_indexer.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+require "open3"
+require "tty-progressbar"
+
+module Docyard
+  module Search
+    class DevIndexer
+      include PagefindSupport
+
+      attr_reader :docs_path, :config, :temp_dir, :pagefind_path
+
+      def initialize(docs_path:, config:)
+        @docs_path = docs_path
+        @config = config
+        @temp_dir = nil
+        @pagefind_path = nil
+      end
+
+      def generate
+        return unless search_enabled?
+        return unless pagefind_available?
+
+        @temp_dir = Dir.mktmpdir("docyard-search-")
+        generate_html_files
+        page_count = run_pagefind
+        @pagefind_path = File.join(temp_dir, "pagefind")
+
+        log_success(page_count)
+        pagefind_path
+      rescue StandardError => e
+        warn "[!] Search index generation failed: #{e.message}"
+        cleanup
+        nil
+      end
+
+      def cleanup
+        return unless temp_dir && Dir.exist?(temp_dir)
+
+        FileUtils.rm_rf(temp_dir)
+      end
+
+      private
+
+      def pagefind_available?
+        result = super
+        warn "[!] Search disabled: Pagefind not found (npm install -g pagefind)" unless result
+        result
+      end
+
+      def generate_html_files
+        markdown_files = Dir.glob(File.join(docs_path, "**", "*.md"))
+        markdown_files = filter_excluded_files(markdown_files)
+        markdown_files = filter_non_indexable_files(markdown_files)
+        renderer = Renderer.new(base_url: "/", config: config)
+
+        progress = TTY::ProgressBar.new(
+          "Indexing search [:bar] :current/:total (:percent)",
+          total: markdown_files.size,
+          width: 50
+        )
+
+        markdown_files.each do |file_path|
+          generate_html_file(file_path, renderer)
+          progress.advance
+        end
+      end
+
+      def filter_excluded_files(files)
+        exclude_patterns = config.search.exclude || []
+        return files if exclude_patterns.empty?
+
+        files.reject do |file_path|
+          url_path = file_to_url_path(file_path)
+          exclude_patterns.any? { |pattern| File.fnmatch(pattern, url_path, File::FNM_PATHNAME) }
+        end
+      end
+
+      def filter_non_indexable_files(files)
+        files.reject do |file_path|
+          content = File.read(file_path)
+          markdown = Markdown.new(content)
+          frontmatter = markdown.frontmatter
+
+          uses_splash_template?(frontmatter)
+        end
+      end
+
+      def uses_splash_template?(frontmatter)
+        return true if frontmatter["template"] == "splash"
+        return true if frontmatter.key?("landing")
+
+        frontmatter.key?("hero") || frontmatter.key?("features")
+      end
+
+      def file_to_url_path(file_path)
+        relative_path = file_path.delete_prefix("#{docs_path}/")
+        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 generate_html_file(markdown_file, renderer)
+        relative_path = markdown_file.delete_prefix("#{docs_path}/")
+        output_path = determine_output_path(relative_path)
+
+        html = renderer.render_file(markdown_file, branding: branding_options)
+
+        FileUtils.mkdir_p(File.dirname(output_path))
+        File.write(output_path, html)
+      end
+
+      def determine_output_path(relative_path)
+        base_name = File.basename(relative_path, ".md")
+        dir_name = File.dirname(relative_path)
+
+        if base_name == "index"
+          File.join(temp_dir, dir_name, "index.html")
+        else
+          File.join(temp_dir, dir_name, base_name, "index.html")
+        end
+      end
+
+      def branding_options
+        BrandingResolver.new(config).resolve
+      end
+
+      def run_pagefind
+        args = build_pagefind_args(temp_dir)
+        stdout, stderr, status = Open3.capture3("npx", *args)
+
+        raise "Pagefind failed: #{stderr}" unless status.success?
+
+        extract_page_count(stdout)
+      end
+
+      def extract_page_count(output)
+        match = output.match(/Indexed (\d+) page/i)
+        match ? match[1].to_i : 0
+      end
+
+      def log_success(page_count)
+        puts "=> Search index generated (#{page_count} pages indexed)"
+        puts "=> Temp directory: #{temp_dir}" if ENV["DOCYARD_DEBUG"]
+      end
+    end
+  end
+end

data/lib/docyard/search/pagefind_support.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Docyard
+  module Search
+    module PagefindSupport
+      def search_enabled?
+        config.search.enabled != false
+      end
+
+      def pagefind_available?
+        _stdout, _stderr, status = Open3.capture3("npx", "pagefind", "--version")
+        status.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      def build_pagefind_args(site_dir)
+        args = ["pagefind", "--site", site_dir]
+
+        exclusions = config.search.exclude || []
+        exclusions.each do |pattern|
+          next if pattern.start_with?("/")
+
+          args += ["--exclude-selectors", pattern]
+        end
+
+        args
+      end
+    end
+  end
+end