docyard 0.7.0 → 0.9.0

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

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+
+module Docyard
+  module Components
+    module Processors
+      class VideoEmbedProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        YOUTUBE_PATTERN = /::youtube\[([^\]]+)\](?:\{([^}]*)\})?/
+        VIMEO_PATTERN = /::vimeo\[([^\]]+)\](?:\{([^}]*)\})?/
+        VIDEO_PATTERN = /::video\[([^\]]+)\](?:\{([^}]*)\})?/
+
+        self.priority = 5
+
+        def preprocess(content)
+          process_outside_code_blocks(content) do |segment|
+            process_video_embeds(segment)
+          end
+        end
+
+        private
+
+        def process_video_embeds(content)
+          result = content.gsub(YOUTUBE_PATTERN) do
+            video_id = Regexp.last_match(1)
+            attrs_string = Regexp.last_match(2)
+            build_youtube_embed(video_id, parse_attributes(attrs_string))
+          end
+
+          result = result.gsub(VIMEO_PATTERN) do
+            video_id = Regexp.last_match(1)
+            attrs_string = Regexp.last_match(2)
+            build_vimeo_embed(video_id, parse_attributes(attrs_string))
+          end
+
+          result.gsub(VIDEO_PATTERN) do
+            src = Regexp.last_match(1)
+            attrs_string = Regexp.last_match(2)
+            build_native_video(src, parse_attributes(attrs_string))
+          end
+        end
+
+        def parse_attributes(attrs_string)
+          return {} if attrs_string.nil? || attrs_string.empty?
+
+          attrs = {}
+
+          attrs_string.scan(/(\w+)="([^"]*)"/) do |key, value|
+            attrs[key] = value
+          end
+
+          %w[autoplay loop muted nofullscreen controls playsinline].each do |flag|
+            attrs[flag] = true if attrs_string.match?(/\b#{flag}\b/) && !attrs.key?(flag)
+          end
+
+          attrs
+        end
+
+        def build_youtube_embed(video_id, attrs)
+          params = youtube_params(attrs)
+          url = "https://www.youtube-nocookie.com/embed/#{escape_attr(video_id)}"
+          url += "?#{params.join('&')}" unless params.empty?
+
+          build_iframe(url, attrs, "youtube")
+        end
+
+        def build_vimeo_embed(video_id, attrs)
+          params = vimeo_params(attrs)
+          url = "https://player.vimeo.com/video/#{escape_attr(video_id)}"
+          url += "?#{params.join('&')}" unless params.empty?
+
+          build_iframe(url, attrs, "vimeo")
+        end
+
+        def build_native_video(src, attrs)
+          wrapper_style = build_wrapper_style(attrs)
+          video_attrs = build_video_attrs(src, attrs)
+
+          "\n\n" \
+            "<div class=\"docyard-video docyard-video--native\"#{wrapper_style} markdown=\"0\">\n  " \
+            "<video #{video_attrs.join(' ')}></video>\n" \
+            "</div>" \
+            "\n\n"
+        end
+
+        def build_video_attrs(src, attrs)
+          video_attrs = ["src=\"#{escape_attr(src)}\""]
+          video_attrs.concat(video_optional_attrs(attrs))
+          video_attrs.concat(video_boolean_attrs(attrs))
+          video_attrs
+        end
+
+        def video_optional_attrs(attrs)
+          result = []
+          result << "poster=\"#{escape_attr(attrs['poster'])}\"" if attrs["poster"]
+          result << "preload=\"#{escape_attr(attrs['preload'])}\"" if attrs["preload"]
+          result
+        end
+
+        def video_boolean_attrs(attrs)
+          result = []
+          result << "controls" unless controls_disabled?(attrs)
+          result << "autoplay" if attrs["autoplay"]
+          result << "muted" if attrs["muted"]
+          result << "loop" if attrs["loop"]
+          result << "playsinline" if attrs["playsinline"]
+          result
+        end
+
+        def controls_disabled?(attrs)
+          ["false", false].include?(attrs["controls"])
+        end
+
+        def youtube_params(attrs)
+          params = []
+          params << "autoplay=1" if attrs["autoplay"]
+          params << "loop=1" if attrs["loop"]
+          params << "mute=1" if attrs["muted"]
+          params << "controls=0" if ["false", false].include?(attrs["controls"])
+          params << "start=#{attrs['start']}" if attrs["start"]
+          params << "rel=0"
+          params
+        end
+
+        def vimeo_params(attrs)
+          params = []
+          params << "autoplay=1" if attrs["autoplay"]
+          params << "loop=1" if attrs["loop"]
+          params << "muted=1" if attrs["muted"]
+          params << "controls=0" if ["false", false].include?(attrs["controls"])
+          params << "dnt=1"
+          params
+        end
+
+        def build_iframe(url, attrs, provider)
+          wrapper_style = build_wrapper_style(attrs)
+          iframe_attrs = build_iframe_attrs(url, attrs, provider)
+
+          "\n\n" \
+            "<div class=\"docyard-video docyard-video--#{provider}\"#{wrapper_style} markdown=\"0\">\n  " \
+            "<iframe #{iframe_attrs.join(' ')}></iframe>\n" \
+            "</div>" \
+            "\n\n"
+        end
+
+        def build_wrapper_style(attrs)
+          return "" unless attrs["width"] || attrs["height"]
+
+          styles = []
+          styles << "max-width: #{escape_attr(attrs['width'])}px" if attrs["width"]
+          styles << "height: #{escape_attr(attrs['height'])}px" if attrs["height"]
+          " style=\"#{styles.join('; ')}\""
+        end
+
+        def build_iframe_attrs(url, attrs, provider)
+          iframe_attrs = [
+            "src=\"#{url}\"",
+            "title=\"#{escape_attr(attrs['title'] || default_title(provider))}\"",
+            "frameborder=\"0\""
+          ]
+
+          iframe_attrs << "allow=\"#{build_allow_attr(attrs)}\""
+          iframe_attrs << "allowfullscreen" unless attrs["nofullscreen"]
+
+          iframe_attrs
+        end
+
+        def build_allow_attr(attrs)
+          permissions = %w[encrypted-media picture-in-picture web-share]
+          permissions.unshift("autoplay") if attrs["autoplay"]
+          permissions << "fullscreen" unless attrs["nofullscreen"]
+          permissions.join("; ")
+        end
+
+        def default_title(provider)
+          case provider
+          when "youtube" then "YouTube video player"
+          when "vimeo" then "Vimeo video player"
+          else "Video player"
+          end
+        end
+
+        def escape_attr(text)
+          text.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub('"', "&quot;")
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/support/code_group/html_builder.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "../code_block/icon_detector"
+require_relative "../../../rendering/icons"
+
+module Docyard
+  module Components
+    module Support
+      module CodeGroup
+        class HtmlBuilder
+          def initialize(blocks, group_id)
+            @blocks = blocks
+            @group_id = group_id
+          end
+
+          def build
+            <<~HTML
+              <div class="docyard-code-group" data-code-group="#{@group_id}">
+                <div class="docyard-code-group__tabs-wrapper">
+                  <div class="docyard-code-group__tabs-scroll-container">
+                    <div role="tablist" aria-label="Code examples" class="docyard-code-group__tabs">
+                      #{build_tabs}
+                      <div class="docyard-code-group__indicator" aria-hidden="true"></div>
+                    </div>
+                  </div>
+                  #{build_copy_button}
+                </div>
+                <div class="docyard-code-group__panels">
+                  #{build_panels}
+                </div>
+              </div>
+            HTML
+          end
+
+          private
+
+          def build_tabs
+            @blocks.each_with_index.map do |block, index|
+              build_tab(block, index)
+            end.join("\n")
+          end
+
+          def build_tab(block, index)
+            selected = index.zero? ? "true" : "false"
+            tabindex = index.zero? ? "0" : "-1"
+            icon_html = render_icon(block[:lang])
+            <<~HTML.strip
+              <button
+                role="tab"
+                aria-selected="#{selected}"
+                aria-controls="cg-panel-#{@group_id}-#{index}"
+                id="cg-tab-#{@group_id}-#{index}"
+                class="docyard-code-group__tab"
+                tabindex="#{tabindex}"
+                data-label="#{escape_html(block[:label])}"
+              >#{icon_html}#{escape_html(block[:label])}</button>
+            HTML
+          end
+
+          def render_icon(lang)
+            return "" if lang.nil? || lang.empty?
+
+            icon, icon_source = CodeBlock::IconDetector.auto_detect_icon(lang)
+            return "" unless icon && icon_source == "file-extension"
+
+            Icons.render_file_extension(icon) || ""
+          end
+
+          def build_copy_button
+            copy_icon = Icons.render("copy", "regular") || ""
+            <<~HTML.strip
+              <button class="docyard-code-group__copy" aria-label="Copy code to clipboard">
+                <span class="docyard-code-group__copy-icon">#{copy_icon}</span>
+                <span class="docyard-code-group__copy-text">Copy</span>
+              </button>
+            HTML
+          end
+
+          def build_panels
+            @blocks.each_with_index.map do |block, index|
+              build_panel(block, index)
+            end.join("\n")
+          end
+
+          def build_panel(block, index)
+            hidden = index.zero? ? "false" : "true"
+            code_text = escape_html_attribute(block[:code_text] || "")
+            <<~HTML.strip
+              <div
+                role="tabpanel"
+                id="cg-panel-#{@group_id}-#{index}"
+                aria-labelledby="cg-tab-#{@group_id}-#{index}"
+                aria-hidden="#{hidden}"
+                class="docyard-code-group__panel"
+                tabindex="0"
+                data-code="#{code_text}"
+              >#{block[:content]}</div>
+            HTML
+          end
+
+          def escape_html(text)
+            text.to_s
+              .gsub("&", "&amp;")
+              .gsub("<", "&lt;")
+              .gsub(">", "&gt;")
+              .gsub('"', "&quot;")
+          end
+
+          def escape_html_attribute(text)
+            text.to_s
+              .gsub("&", "&amp;")
+              .gsub("<", "&lt;")
+              .gsub(">", "&gt;")
+              .gsub('"', "&quot;")
+              .gsub("'", "&#39;")
+              .gsub("\n", "&#10;")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docyard/components/support/markdown_code_block_helper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    module Support
+      module MarkdownCodeBlockHelper
+        FENCED_CODE_BLOCK_REGEX = /^(`{3,}|~{3,})[^\n]*\n.*?^\1\s*$/m
+
+        def process_outside_code_blocks(content)
+          segments = split_by_code_blocks(content)
+
+          segments.map do |segment|
+            segment[:type] == :code ? segment[:content] : yield(segment[:content])
+          end.join
+        end
+
+        def find_code_block_ranges(content, exclude_language: nil)
+          ranges = []
+          content.scan(FENCED_CODE_BLOCK_REGEX) do
+            match = Regexp.last_match
+            next if exclude_language && match[0] =~ /\A[`~]{3,}#{exclude_language}\b/
+
+            ranges << (match.begin(0)...match.end(0))
+          end
+          ranges
+        end
+
+        def inside_code_block?(position, ranges)
+          ranges.any? { |range| range.cover?(position) }
+        end
+
+        private
+
+        def split_by_code_blocks(content)
+          segments = []
+          current_pos = 0
+
+          content.scan(FENCED_CODE_BLOCK_REGEX) do
+            match = Regexp.last_match
+            match_start = match.begin(0)
+            match_end = match.end(0)
+
+            segments << { type: :text, content: content[current_pos...match_start] } if match_start > current_pos
+
+            segments << { type: :code, content: content[match_start...match_end] }
+            current_pos = match_end
+          end
+
+          segments << { type: :text, content: content[current_pos..] } if current_pos < content.length
+
+          segments.empty? ? [{ type: :text, content: content }] : segments
+        end
+      end
+    end
+  end
+end

data/lib/docyard/config/branding_resolver.rb

@@ -1,11 +1,22 @@
 # frozen_string_literal: true
 
+require_relative "logo_detector"
+
 module Docyard
   class BrandingResolver
     def initialize(config)
       @config = config
     end
 
+    SOCIAL_ICON_MAP = {
+      "x" => "x-logo", "twitter" => "x-logo", "discord" => "discord-logo",
+      "linkedin" => "linkedin-logo", "youtube" => "youtube-logo", "instagram" => "instagram-logo",
+      "facebook" => "facebook-logo", "tiktok" => "tiktok-logo", "twitch" => "twitch-logo",
+      "reddit" => "reddit-logo", "mastodon" => "mastodon-logo", "threads" => "threads-logo",
+      "pinterest" => "pinterest-logo", "medium" => "medium-logo", "slack" => "slack-logo",
+      "gitlab" => "gitlab-logo"
+    }.freeze
+
     def resolve
       return default_branding unless config
 
@@ -23,52 +34,145 @@ module Docyard
         logo: Constants::DEFAULT_LOGO_PATH,
         logo_dark: Constants::DEFAULT_LOGO_DARK_PATH,
         favicon: nil,
-        display_logo: true,
-        display_title: true
+        credits: true,
+        social: []
       }
     end
 
     def config_branding_options
-      site_options.merge(logo_options).merge(search_options).merge(appearance_options)
+      site_options
+        .merge(logo_options)
+        .merge(search_options)
+        .merge(credits_options)
+        .merge(social_options)
+        .merge(navigation_options)
+        .merge(tabs_options)
+        .merge(announcement_options)
     end
 
     def site_options
       {
-        site_title: config.site.title || Constants::DEFAULT_SITE_TITLE,
-        site_description: config.site.description || "",
-        favicon: config.branding.favicon
+        site_title: config.title || Constants::DEFAULT_SITE_TITLE,
+        site_description: config.description || "",
+        favicon: config.branding.favicon || LogoDetector.auto_detect_favicon
       }
     end
 
     def logo_options
       branding = config.branding
+      logo = branding.logo || LogoDetector.auto_detect_logo
+      has_custom_logo = !logo.nil?
       {
-        logo: resolve_logo(branding.logo, branding.logo_dark),
-        logo_dark: resolve_logo_dark(branding.logo, branding.logo_dark)
+        logo: logo || Constants::DEFAULT_LOGO_PATH,
+        logo_dark: LogoDetector.detect_dark_logo(logo) || Constants::DEFAULT_LOGO_DARK_PATH,
+        has_custom_logo: has_custom_logo
       }
     end
 
     def search_options
       {
         search_enabled: config.search.enabled != false,
-        search_placeholder: config.search.placeholder || "Search documentation..."
+        search_placeholder: config.search.placeholder || "Search..."
+      }
+    end
+
+    def credits_options
+      {
+        credits: config.branding.credits != false,
+        copyright: config.branding.copyright
+      }
+    end
+
+    def social_options
+      socials = config.socials || {}
+      {
+        social: normalize_social_links(socials)
+      }
+    end
+
+    def normalize_social_links(socials)
+      return [] unless socials.is_a?(Hash) && socials.any?
+
+      socials.filter_map { |platform, url| build_social_link(platform.to_s, url) }
+    end
+
+    def build_social_link(platform, url)
+      return if platform == "custom" || !valid_url?(url)
+
+      { platform: platform, url: url, icon: SOCIAL_ICON_MAP[platform] || platform }
+    end
+
+    def valid_url?(url)
+      url.is_a?(String) && !url.strip.empty?
+    end
+
+    def navigation_options
+      cta_items = config.navigation.cta || []
+      {
+        header_ctas: normalize_cta_items(cta_items)
       }
     end
 
-    def appearance_options
-      appearance = config.branding.appearance || {}
+    def normalize_cta_items(items)
+      return [] unless items.is_a?(Array)
+
+      items.first(2).filter_map do |item|
+        next unless item.is_a?(Hash) && item["text"] && item["href"]
+
+        {
+          text: item["text"],
+          href: item["href"],
+          variant: item["variant"] || "primary",
+          external: item["external"] == true
+        }
+      end
+    end
+
+    def tabs_options
+      tab_items = config.tabs || []
       {
-        display_logo: appearance["logo"] != false,
-        display_title: appearance["title"] != false
+        tabs: normalize_tab_items(tab_items),
+        has_tabs: tab_items.any?
       }
     end
 
-    def resolve_logo(logo, logo_dark)
-      logo || logo_dark || Constants::DEFAULT_LOGO_PATH
+    def normalize_tab_items(items)
+      return [] unless items.is_a?(Array)
+
+      items.filter_map do |item|
+        next unless item.is_a?(Hash) && item["text"] && item["href"]
+
+        {
+          text: item["text"],
+          href: item["href"],
+          icon: item["icon"],
+          external: item["external"] == true
+        }
+      end
+    end
+
+    def announcement_options
+      announcement = config.announcement
+      return { announcement: nil } unless announcement
+
+      {
+        announcement: {
+          text: announcement.text,
+          link: announcement.link,
+          button: build_announcement_button(announcement),
+          dismissible: announcement.dismissible != false
+        }
+      }
     end
 
-    def resolve_logo_dark(logo, logo_dark)
-      logo_dark || logo || Constants::DEFAULT_LOGO_DARK_PATH
+    def build_announcement_button(announcement)
+      button = announcement.button
+      return nil unless button.is_a?(Hash) && button["text"]
+
+      {
+        text: button["text"],
+        link: button["link"] || announcement.link
+      }
     end
   end
 end

data/lib/docyard/config/constants.rb

@@ -8,8 +8,9 @@ module Docyard
     CONTENT_TYPE_JS = "application/javascript; charset=utf-8"
 
     RELOAD_ENDPOINT = "/_docyard/reload"
-    ASSETS_PREFIX = "/assets/"
+    DOCYARD_ASSETS_PREFIX = "/_docyard/"
     PAGEFIND_PREFIX = "/pagefind/"
+    PUBLIC_DIR = "docs/public"
 
     INDEX_FILE = "index"
     INDEX_TITLE = "Home"
@@ -18,12 +19,13 @@ module Docyard
     HTML_EXTENSION = ".html"
 
     STATUS_OK = 200
+    STATUS_REDIRECT = 302
     STATUS_NOT_FOUND = 404
     STATUS_INTERNAL_ERROR = 500
 
     DEFAULT_SITE_TITLE = "Documentation"
-    DEFAULT_LOGO_PATH = "assets/logo.svg"
-    DEFAULT_LOGO_DARK_PATH = "assets/logo-dark.svg"
-    DEFAULT_FAVICON_PATH = "assets/favicon.svg"
+    DEFAULT_LOGO_PATH = "_docyard/logo.svg"
+    DEFAULT_LOGO_DARK_PATH = "_docyard/logo-dark.svg"
+    DEFAULT_FAVICON_PATH = "_docyard/favicon.svg"
   end
 end

data/lib/docyard/config/logo_detector.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Docyard
+  module LogoDetector
+    module_function
+
+    def auto_detect_logo
+      detect_public_file("logo", %w[svg png])
+    end
+
+    def auto_detect_favicon
+      detect_public_file("favicon", %w[ico svg png])
+    end
+
+    def detect_public_file(name, extensions)
+      extensions.each do |ext|
+        path = File.join(Constants::PUBLIC_DIR, "#{name}.#{ext}")
+        return "#{name}.#{ext}" if File.exist?(path)
+      end
+      nil
+    end
+
+    def detect_dark_logo(logo)
+      return nil unless logo
+
+      ext = File.extname(logo)
+      base = File.basename(logo, ext)
+      dark_filename = "#{base}-dark#{ext}"
+
+      if File.absolute_path?(logo)
+        dark_path = File.join(File.dirname(logo), dark_filename)
+        File.exist?(dark_path) ? dark_path : logo
+      else
+        dark_path = File.join("docs/public", dark_filename)
+        File.exist?(dark_path) ? dark_filename : logo
+      end
+    end
+  end
+end