docyard 0.8.0 → 0.9.0

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

@@ -2,6 +2,7 @@
 
 require_relative "../../rendering/renderer"
 require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
 require_relative "../support/tabs/parser"
 require "securerandom"
 
@@ -9,6 +10,8 @@ module Docyard
   module Components
     module Processors
       class TabsProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
         self.priority = 15
 
         TabsParser = Support::Tabs::Parser
@@ -16,8 +19,13 @@ module Docyard
         def preprocess(content)
           return content unless content.include?(":::tabs")
 
+          @code_block_ranges = find_code_block_ranges(content)
+
           content.gsub(/^:::[ \t]*tabs[ \t]*\n(.*?)^:::[ \t]*$/m) do
-            process_tabs_block(Regexp.last_match(1))
+            match = Regexp.last_match
+            next match[0] if inside_code_block?(match.begin(0), @code_block_ranges)
+
+            process_tabs_block(match[1])
           end
         end
 

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../base_processor"
+require_relative "../support/markdown_code_block_helper"
+
+module Docyard
+  module Components
+    module Processors
+      class TooltipProcessor < BaseProcessor
+        include Support::MarkdownCodeBlockHelper
+
+        TOOLTIP_PATTERN = /:tooltip\[([^\]]+)\]\{([^}]+)\}/
+        self.priority = 6
+
+        def preprocess(content)
+          process_outside_code_blocks(content) do |segment|
+            segment.gsub(TOOLTIP_PATTERN) do |_match|
+              term = ::Regexp.last_match(1)
+              attributes = parse_attributes(::Regexp.last_match(2))
+              build_tooltip_tag(term, attributes)
+            end
+          end
+        end
+
+        private
+
+        def parse_attributes(attr_string)
+          attributes = {}
+          attr_string.scan(/(\w+)="([^"]*)"/) do |key, value|
+            attributes[key.to_sym] = value
+          end
+          attributes
+        end
+
+        def build_tooltip_tag(term, attributes)
+          description = escape_html(attributes[:description] || "")
+          link = attributes[:link]
+          link_text = attributes[:link_text] || "Learn more"
+
+          data_attrs = %(data-description="#{description}")
+          data_attrs += %( data-link="#{escape_html(link)}") if link
+          data_attrs += %( data-link-text="#{escape_html(link_text)}") if link
+
+          %(<span class="docyard-tooltip" #{data_attrs}>#{term}</span>)
+        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/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,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "logo_detector"
+
 module Docyard
   class BrandingResolver
     def initialize(config)
@@ -45,59 +47,28 @@ module Docyard
         .merge(social_options)
         .merge(navigation_options)
         .merge(tabs_options)
+        .merge(announcement_options)
     end
 
     def site_options
       {
         site_title: config.title || Constants::DEFAULT_SITE_TITLE,
         site_description: config.description || "",
-        favicon: config.branding.favicon || auto_detect_favicon
+        favicon: config.branding.favicon || LogoDetector.auto_detect_favicon
       }
     end
 
     def logo_options
       branding = config.branding
-      logo = branding.logo || auto_detect_logo
+      logo = branding.logo || LogoDetector.auto_detect_logo
       has_custom_logo = !logo.nil?
       {
         logo: logo || Constants::DEFAULT_LOGO_PATH,
-        logo_dark: detect_dark_logo(logo) || Constants::DEFAULT_LOGO_DARK_PATH,
+        logo_dark: LogoDetector.detect_dark_logo(logo) || Constants::DEFAULT_LOGO_DARK_PATH,
         has_custom_logo: has_custom_logo
       }
     end
 
-    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
-
     def search_options
       {
         search_enabled: config.search.enabled != false,
@@ -179,5 +150,29 @@ module Docyard
         }
       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 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/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

data/lib/docyard/config.rb

@@ -29,7 +29,8 @@ module Docyard
       "navigation" => {
         "cta" => [],
         "breadcrumbs" => true
-      }
+      },
+      "announcement" => nil
     }.freeze
 
     attr_reader :data, :file_path
@@ -81,6 +82,10 @@ module Docyard
       @navigation ||= ConfigSection.new(data["navigation"])
     end
 
+    def announcement
+      @announcement ||= data["announcement"] ? ConfigSection.new(data["announcement"]) : nil
+    end
+
     private
 
     def load_config_data

data/lib/docyard/navigation/sidebar/file_resolver.rb

@@ -58,17 +58,29 @@ module Docyard
       end
 
       def build_context(slug, base_path, options)
+        paths = resolve_paths(slug, base_path, options)
+        frontmatter = metadata_extractor.extract_frontmatter_metadata(paths[:file])
+
+        build_context_hash(slug, paths, options, frontmatter)
+      end
+
+      def resolve_paths(slug, base_path, options)
         file_path = File.join(docs_path, base_path, "#{slug}.md")
         url_path = Utils::PathResolver.to_url(File.join(base_path, slug))
-        frontmatter = metadata_extractor.extract_frontmatter_metadata(file_path)
         final_path = options["link"] || options[:link] || url_path
 
+        { file: file_path, final: final_path }
+      end
+
+      def build_context_hash(slug, paths, options, frontmatter)
         {
           slug: slug,
-          text: metadata_extractor.resolve_item_text(slug, file_path, options, frontmatter[:text]),
-          path: final_path,
+          text: metadata_extractor.resolve_item_text(slug, paths[:file], options, frontmatter[:text]),
+          path: paths[:final],
           icon: metadata_extractor.resolve_item_icon(options, frontmatter[:icon]),
-          active: current_path == final_path,
+          badge: frontmatter[:badge],
+          badge_type: frontmatter[:badge_type],
+          active: current_path == paths[:final],
           type: :file,
           section: false
         }

data/lib/docyard/navigation/sidebar/item.rb

@@ -3,7 +3,8 @@
 module Docyard
   module Sidebar
     class Item
-      attr_reader :slug, :text, :icon, :link, :target, :collapsed, :items, :path, :active, :type, :has_index, :section
+      attr_reader :slug, :text, :icon, :link, :target, :collapsed, :items, :path, :active, :type, :has_index, :section,
+                  :badge, :badge_type
 
       DEFAULTS = {
         target: "_self",
@@ -27,6 +28,8 @@ module Docyard
         @text = options[:text]
         @icon = options[:icon]
         @link = options[:link]
+        @badge = options[:badge]
+        @badge_type = options[:badge_type]
       end
 
       def assign_optional_attributes(options)
@@ -88,6 +91,8 @@ module Docyard
           target: target,
           has_index: has_index,
           section: section,
+          badge: badge,
+          badge_type: badge_type,
           children: children.map(&:to_h)
         }
       end