docyard 0.8.0 → 1.0.0

data/lib/docyard/templates/partials/_code_block.html.erb

@@ -2,7 +2,7 @@
   <% if has_title %>
   <div class="docyard-code-block__header">
     <% if @icon %>
-    <span class="docyard-code-block__icon"><% if @icon_source == "file-extension" %><%= icon_file_extension(@icon) %><% elsif @icon_source == "phosphor" %><%= icon(@icon) %><% end %></span>
+    <span class="docyard-code-block__icon"><% if @icon_source == "language" %><%= icon_for_language(@icon) %><% elsif @icon_source == "file-extension" %><%= icon_file_extension(@icon) %><% elsif @icon_source == "phosphor" %><%= icon(@icon) %><% end %></span>
     <% end %>
     <span class="docyard-code-block__title" title="<%= @title %>"><%= @title %></span>
     <button class="docyard-code-block__copy" aria-label="Copy code to clipboard" data-code="<%= @code_text %>">

data/lib/docyard/templates/partials/_feedback.html.erb

@@ -0,0 +1,14 @@
+<% if @feedback_enabled %>
+<div class="feedback" data-pagefind-ignore>
+  <p class="feedback__question"><%= @feedback_question %></p>
+  <div class="feedback__buttons">
+    <button type="button" class="feedback__btn" data-feedback="yes" aria-label="Yes, this page was helpful">
+      <%= icon(:thumbs_up) %>
+    </button>
+    <button type="button" class="feedback__btn" data-feedback="no" aria-label="No, this page was not helpful">
+      <%= icon(:thumbs_down) %>
+    </button>
+  </div>
+  <p class="feedback__thanks" aria-live="polite" hidden>Thanks for your feedback!</p>
+</div>
+<% end %>

data/lib/docyard/templates/partials/_footer.html.erb

@@ -17,7 +17,7 @@
   %>
   <div class="<%= footer_class %>">
     <% if @credits %>
-    <a href="https://docyard.org" target="_blank" rel="noopener noreferrer" class="footer-attribution">Built with Docyard</a>
+    <a href="https://docyard.dev" target="_blank" rel="noopener noreferrer" class="footer-attribution">Built with Docyard</a>
     <% end %>
 
     <% if has_footer_links %>

data/lib/docyard/templates/partials/_head.html.erb

@@ -5,18 +5,93 @@
 <title><%= @page_title %> | <%= @site_title %></title>
 <link rel="icon" href="<%= asset_path(@favicon) %>" type="image/svg+xml">
 
+<% if @og_enabled %>
+<link rel="canonical" href="<%= @og_url %>">
+
+<meta property="og:type" content="website">
+<meta property="og:site_name" content="<%= @site_title %>">
+<meta property="og:title" content="<%= @page_title %>">
+<meta property="og:url" content="<%= @og_url %>">
+<% if @og_description && !@og_description.empty? %>
+<meta property="og:description" content="<%= @og_description %>">
+<% end %>
+<% if @og_image %>
+<meta property="og:image" content="<%= @og_image %>">
+<% end %>
+
+<meta name="twitter:card" content="<%= @og_image ? 'summary_large_image' : 'summary' %>">
+<meta name="twitter:title" content="<%= @page_title %>">
+<% if @og_description && !@og_description.empty? %>
+<meta name="twitter:description" content="<%= @og_description %>">
+<% end %>
+<% if @og_image %>
+<meta name="twitter:image" content="<%= @og_image %>">
+<% end %>
+<% if @og_twitter %>
+<meta name="twitter:site" content="@<%= @og_twitter.delete_prefix('@') %>">
+<% end %>
+<% end %>
+
 <link rel="preload" href="/_docyard/fonts/Inter-Variable.ttf" as="font" type="font/ttf" crossorigin>
 
+<%= render_partial('_icon_library') %>
+
 <script>
   (function() {
-    const theme = localStorage.getItem('theme') ||
-                 (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
-    document.documentElement.classList.toggle('dark', theme === 'dark');
+    var html = document.documentElement;
+
+    html.classList.add('no-transition');
+
+    var theme = localStorage.getItem('theme') ||
+                (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+    html.classList.toggle('dark', theme === 'dark');
 
     if (localStorage.getItem('docyard_sidebar_collapsed') === 'true') {
-      document.documentElement.classList.add('sidebar-collapsed');
+      html.classList.add('sidebar-collapsed');
     }
+
+    var BANNER_KEY = 'docyard-announcement-dismissed';
+    try {
+      var dismissed = localStorage.getItem(BANNER_KEY);
+      if (dismissed) {
+        var dismissedAt = parseInt(dismissed, 10);
+        var sevenDaysAgo = Date.now() - (7 * 24 * 60 * 60 * 1000);
+        if (dismissedAt > sevenDaysAgo) {
+          html.classList.add('banner-dismissed');
+        }
+      }
+    } catch (e) {}
+
+    requestAnimationFrame(function() {
+      requestAnimationFrame(function() {
+        html.classList.remove('no-transition');
+      });
+    });
   })();
 </script>
 
 <link rel="stylesheet" href="/_docyard/css/main.css">
+
+<% if @primary_color && (@primary_color[:light] || @primary_color[:dark]) %>
+<style>
+<% light_color = @primary_color[:light] %>
+<% dark_color = @primary_color[:dark] || light_color %>
+<% if light_color %>
+:root {
+  --primary: <%= light_color %>;
+  --sidebar-primary: <%= light_color %>;
+}
+.dark {
+  --primary: <%= dark_color %>;
+  --sidebar-primary: <%= dark_color %>;
+}
+<% elsif dark_color %>
+.dark {
+  --primary: <%= dark_color %>;
+  --sidebar-primary: <%= dark_color %>;
+}
+<% end %>
+</style>
+<% end %>
+
+<%= render_partial('_analytics') %>

data/lib/docyard/templates/partials/_icon_library.html.erb

@@ -0,0 +1,8 @@
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/regular/style.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/bold/style.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/fill/style.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/light/style.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/thin/style.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.2/src/duotone/style.css">
+
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/devicon.min.css">

data/lib/docyard/templates/partials/_nav_group.html.erb

@@ -7,6 +7,9 @@
           <span class="nav-item-icon"><%= icon(@icon) %></span>
         <% end %>
         <span class="nav-item-text"><%= @title %></span>
+        <% if @badge %>
+          <span class="docyard-badge docyard-badge--<%= @badge_type || 'default' %>"><%= @badge %></span>
+        <% end %>
       </span>
       <span class="nav-group-icon"><%= icon(:caret_right) %></span>
     </a>
@@ -17,6 +20,9 @@
           <span class="nav-item-icon"><%= icon(@icon) %></span>
         <% end %>
         <span class="nav-item-text"><%= @title %></span>
+        <% if @badge %>
+          <span class="docyard-badge docyard-badge--<%= @badge_type || 'default' %>"><%= @badge %></span>
+        <% end %>
       </span>
       <span class="nav-group-icon"><%= icon(:caret_right) %></span>
     </button>

data/lib/docyard/templates/partials/_nav_leaf.html.erb

@@ -3,6 +3,9 @@
     <span class="nav-item-icon"><%= icon(@icon) %></span>
   <% end %>
   <span class="nav-item-text"><%= @title %></span>
+  <% if @badge %>
+    <span class="docyard-badge docyard-badge--<%= @badge_type || 'default' %>"><%= @badge %></span>
+  <% end %>
   <% if @target == "_blank" %>
     <span class="nav-item-external"><%= icon(:link_external) %></span>
   <% end %>

data/lib/docyard/templates/partials/_page_actions.html.erb

@@ -0,0 +1,21 @@
+<% if @raw_markdown || @show_edit_link || @show_last_updated %>
+<div class="page-actions">
+  <% if @raw_markdown %>
+  <button type="button" class="page-actions__copy-btn" data-copy-page>
+    <%= icon(:copy) %>
+    <span class="page-actions__copy-text">Copy page</span>
+  </button>
+  <% end %>
+  <% if @show_edit_link && @edit_url %>
+  <a href="<%= @edit_url %>" class="page-actions__edit-link" target="_blank" rel="noopener noreferrer">
+    <%= icon(:pencil_simple_line) %>
+    Edit this page
+  </a>
+  <% end %>
+  <% if @show_last_updated && @last_updated %>
+  <div class="page-actions__last-updated">
+    Last updated <time datetime="<%= @last_updated[:iso] %>" title="<%= @last_updated[:formatted] %>"><%= @last_updated[:relative] %></time>
+  </div>
+  <% end %>
+</div>
+<% end %>

data/lib/docyard/templates/partials/_scripts.html.erb

@@ -2,6 +2,9 @@
 <%= render_partial('_search_modal') %>
 <% end %>
 
-<script src="/_docyard/js/theme.js"></script>
-<script src="/_docyard/js/components.js"></script>
-<script src="/_docyard/js/reload.js"></script>
+<script src="/_docyard/js/theme.js" defer></script>
+<script src="/_docyard/js/components.js" defer></script>
+<% if @dev_mode %>
+<script>window.__DOCYARD_SSE_PORT__ = <%= @sse_port %>;</script>
+<script src="/_docyard/js/hot-reload.js" defer></script>
+<% end %>

data/lib/docyard/templates/partials/_step.html.erb

@@ -0,0 +1,14 @@
+<div class="docyard-step<%= ' docyard-step--last' if @is_last %>">
+  <div class="docyard-step__indicator">
+    <span class="docyard-step__number"><%= @number %></span>
+    <% unless @is_last %><div class="docyard-step__connector"></div><% end %>
+  </div>
+  <div class="docyard-step__content">
+    <h3 class="docyard-step__title"><%= @title %></h3>
+    <% unless @content_html.empty? %>
+    <div class="docyard-step__body">
+      <%= @content_html %>
+    </div>
+    <% end %>
+  </div>
+</div>

data/lib/docyard/templates/partials/_tabs.html.erb

@@ -9,10 +9,13 @@
           id="tab-<%= @group_id %>-<%= index %>"
           class="docyard-tabs__tab"
           tabindex="<%= index == 0 ? '0' : '-1' %>"
+          data-tab-name="<%= tab[:name].downcase %>"
         >
           <% if tab[:icon] %>
             <span class="docyard-tabs__icon">
-              <% if tab[:icon_source] == "file-extension" %>
+              <% if tab[:icon_source] == "language" %>
+                <%= icon_for_language(tab[:icon]) %>
+              <% elsif tab[:icon_source] == "file-extension" %>
                 <%= icon_file_extension(tab[:icon]) %>
               <% elsif tab[:icon_source] == "phosphor" %>
                 <%= icon(tab[:icon]) %>

data/lib/docyard/utils/git_info.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Docyard
+  module Utils
+    class GitInfo
+      TIME_UNITS = [
+        [60, "minute"],
+        [3600, "hour"],
+        [86_400, "day"],
+        [604_800, "week"],
+        [2_592_000, "month"],
+        [31_536_000, "year"]
+      ].freeze
+
+      class << self
+        attr_accessor :timestamp_cache
+
+        def prefetch_timestamps(docs_path = "docs")
+          return unless git_repository?
+
+          @timestamp_cache = fetch_all_timestamps(docs_path)
+        end
+
+        def clear_cache
+          @timestamp_cache = nil
+        end
+
+        def cached_timestamp(file_path)
+          return nil unless @timestamp_cache
+
+          @timestamp_cache[file_path]
+        end
+
+        def git_repository?
+          File.directory?(".git") || system("git", "rev-parse", "--git-dir", out: File::NULL, err: File::NULL)
+        end
+
+        private
+
+        def fetch_all_timestamps(docs_path)
+          output, _, status = Open3.capture3("git", "log", "--pretty=format:%cI", "--name-only", "--", "#{docs_path}/")
+          return {} unless status.success?
+
+          parse_git_log_output(output)
+        end
+
+        def parse_git_log_output(output)
+          timestamps = {}
+          current_timestamp = nil
+
+          output.each_line do |line|
+            line = line.strip
+            next if line.empty?
+
+            if line.match?(/^\d{4}-\d{2}-\d{2}T/)
+              current_timestamp = Time.parse(line)
+            elsif current_timestamp && !timestamps.key?(line)
+              timestamps[line] = current_timestamp
+            end
+          end
+
+          timestamps
+        end
+      end
+
+      attr_reader :repo_url, :branch, :edit_path
+
+      def initialize(repo_url:, branch: "main", edit_path: "docs")
+        @repo_url = repo_url
+        @branch = branch
+        @edit_path = edit_path
+      end
+
+      def edit_url(file_path)
+        return nil unless repo_url
+
+        relative_path = extract_relative_path(file_path)
+        return nil unless relative_path
+
+        normalized_url = repo_url.chomp("/")
+        "#{normalized_url}/edit/#{branch}/#{edit_path}/#{relative_path}"
+      end
+
+      def last_updated(file_path)
+        return nil unless file_path && File.exist?(file_path)
+        return nil unless self.class.git_repository?
+
+        timestamp = git_last_commit_time(file_path)
+        return nil unless timestamp
+
+        {
+          time: timestamp,
+          iso: timestamp.iso8601,
+          formatted: format_datetime(timestamp),
+          formatted_short: format_date_short(timestamp),
+          relative: relative_time(timestamp)
+        }
+      end
+
+      private
+
+      def extract_relative_path(file_path)
+        return nil unless file_path
+
+        match = file_path.match(%r{#{Regexp.escape(edit_path)}/(.+)$})
+        match ? match[1] : nil
+      end
+
+      def git_last_commit_time(file_path)
+        cached = self.class.cached_timestamp(file_path)
+        return cached if cached
+
+        fetch_single_timestamp(file_path)
+      end
+
+      def fetch_single_timestamp(file_path)
+        output, _, status = Open3.capture3("git", "log", "-1", "--format=%cI", "--", file_path)
+        return nil unless status.success?
+        return nil if output.strip.empty?
+
+        Time.parse(output.strip)
+      rescue ArgumentError
+        nil
+      end
+
+      def format_datetime(time)
+        time.strftime("%B %-d, %Y at %-I:%M %p")
+      end
+
+      def format_date_short(time)
+        time.strftime("%b %-d, %Y")
+      end
+
+      def relative_time(time)
+        seconds = Time.now - time
+        return "just now" if seconds < TIME_UNITS.first.first
+
+        divisor, unit = find_time_unit(seconds)
+        pluralize((seconds / divisor).to_i, unit)
+      end
+
+      def find_time_unit(seconds)
+        TIME_UNITS.reverse_each do |threshold, unit|
+          return [threshold, unit] if seconds >= threshold
+        end
+        TIME_UNITS.first
+      end
+
+      def pluralize(count, word)
+        suffix = count == 1 ? "" : "s"
+        "#{count} #{word}#{suffix} ago"
+      end
+    end
+  end
+end

data/lib/docyard/utils/hash_utils.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Utils
+    module HashUtils
+      module_function
+
+      def deep_merge(hash1, hash2)
+        hash1.merge(hash2) do |_key, v1, v2|
+          if v2.nil?
+            v1
+          elsif v1.is_a?(Hash) && v2.is_a?(Hash)
+            deep_merge(v1, v2)
+          else
+            v2
+          end
+        end
+      end
+
+      def deep_dup(hash)
+        hash.transform_values do |value|
+          case value
+          when Hash then deep_dup(value)
+          when Array then value.map { |v| v.is_a?(Hash) ? deep_dup(v) : v }
+          else value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docyard/utils/html_helpers.rb

@@ -3,6 +3,14 @@
 module Docyard
   module Utils
     module HtmlHelpers
+      def escape_html(text)
+        text.to_s
+          .gsub("&", "&")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+          .gsub('"', "&quot;")
+      end
+
       def escape_html_attribute(text)
         text.gsub('"', "&quot;")
           .gsub("'", "&#39;")

data/lib/docyard/utils/logging.rb

@@ -15,6 +15,32 @@ module Docyard
         logger.level = Logger.const_get(level.to_s.upcase)
       end
 
+      def start_buffering
+        @buffered_warnings = []
+        @buffering = true
+      end
+
+      def stop_buffering
+        @buffering = false
+        warnings = @buffered_warnings || []
+        @buffered_warnings = []
+        warnings
+      end
+
+      def buffering?
+        @buffering == true
+      end
+
+      def buffer_warning(message)
+        @buffered_warnings ||= []
+        @buffered_warnings << message
+      end
+
+      def flush_warnings
+        warnings = stop_buffering
+        warnings.each { |msg| logger.warn(msg) }
+      end
+
       private
 
       def default_logger
@@ -25,9 +51,24 @@ module Docyard
       end
 
       def log_formatter
-        proc do |severity, datetime, _progname, msg|
-          timestamp = datetime.strftime("%Y-%m-%d %H:%M:%S")
-          "[#{timestamp}] [Docyard] [#{severity}] #{msg}\n"
+        proc do |severity, _datetime, _progname, msg|
+          if severity == "WARN" && buffering?
+            buffer_warning(msg)
+            nil
+          else
+            format_message(severity, msg)
+          end
+        end
+      end
+
+      def format_message(severity, msg)
+        case severity
+        when "DEBUG"
+          "[DEBUG] #{msg}\n"
+        when "INFO"
+          "#{msg}\n"
+        else
+          "[#{severity}] #{msg}\n"
         end
       end
     end

data/lib/docyard/utils/path_resolver.rb

@@ -16,16 +16,6 @@ module Docyard
         normalized = "/#{normalized}" unless normalized.start_with?("/")
         normalized
       end
-
-      def self.to_url(relative_path)
-        normalize(relative_path)
-      end
-
-      def self.ancestor?(parent_path, child_path)
-        return false if parent_path.nil?
-
-        child_path.start_with?(parent_path) && child_path != parent_path
-      end
     end
   end
 end

data/lib/docyard/utils/path_utils.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Docyard
+  module Utils
+    module PathUtils
+      module_function
+
+      def sanitize_url_path(request_path)
+        decoded = decode_path(request_path)
+        clean = decoded.delete_prefix("/").delete_suffix("/")
+        clean = "index" if clean.empty?
+        clean.delete_suffix(".md")
+      end
+
+      def safe_path?(requested_path, base_dir)
+        return false if requested_path.nil? || base_dir.nil?
+
+        expanded_base = File.expand_path(base_dir)
+        expanded_path = File.expand_path(requested_path, base_dir)
+        expanded_path.start_with?("#{expanded_base}/") || expanded_path == expanded_base
+      end
+
+      def resolve_safe_path(relative_path, base_dir)
+        return nil if relative_path.nil? || base_dir.nil?
+
+        decoded = decode_path(relative_path)
+        full_path = File.join(base_dir, decoded)
+        expanded = File.expand_path(full_path)
+        expanded_base = File.expand_path(base_dir)
+
+        return nil unless expanded.start_with?("#{expanded_base}/")
+
+        expanded
+      end
+
+      def decode_path(path)
+        decoded = URI.decode_www_form_component(path.to_s)
+        decoded.gsub(/\\+/, "/")
+      rescue ArgumentError
+        path.to_s
+      end
+
+      def markdown_file_to_url(file_path, docs_path)
+        relative_path = file_path.delete_prefix("#{docs_path}/")
+        relative_path_to_url(relative_path)
+      end
+
+      def relative_path_to_url(relative_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 markdown_to_html_output(relative_path, output_dir)
+        base_name = File.basename(relative_path, ".md")
+        dir_name = File.dirname(relative_path)
+
+        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
+    end
+  end
+end

data/lib/docyard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docyard
-  VERSION = "0.8.0"
+  VERSION = "1.0.0"
 end

data/lib/docyard.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "docyard/version"
-require_relative "docyard/config/constants"
-require_relative "docyard/utils/errors"
+require_relative "docyard/constants"
+require_relative "docyard/errors"
 require_relative "docyard/utils/logging"
 
 require_relative "docyard/utils/text_formatter"