docyard 0.9.0 → 1.0.0

data/lib/docyard/server/rack_application.rb

@@ -2,24 +2,26 @@
 
 require "json"
 require "rack"
+require_relative "../navigation/page_navigation_builder"
 require_relative "../navigation/sidebar_builder"
-require_relative "../navigation/prev_next_builder"
-require_relative "../navigation/breadcrumb_builder"
 require_relative "../config/branding_resolver"
-require_relative "../config/constants"
+require_relative "../constants"
 require_relative "../rendering/template_resolver"
 require_relative "../routing/fallback_resolver"
 require_relative "pagefind_handler"
 
 module Docyard
   class RackApplication
-    def initialize(docs_path:, file_watcher:, config: nil, pagefind_path: nil)
+    def initialize(docs_path:, config: nil, pagefind_path: nil, sse_port: nil, sidebar_cache: nil)
       @docs_path = docs_path
-      @file_watcher = file_watcher
       @config = config
+      @sse_port = sse_port
+      @dev_mode = !sse_port.nil?
+      @sidebar_cache = sidebar_cache
       @router = Router.new(docs_path: docs_path)
-      @renderer = Renderer.new(base_url: config&.build&.base || "/", config: config)
-      @asset_handler = AssetHandler.new
+      @renderer = Renderer.new(base_url: config&.build&.base || "/", config: config, dev_mode: @dev_mode,
+                               sse_port: sse_port)
+      @asset_handler = AssetHandler.new(public_dir: config&.public_dir || "docs/public")
       @pagefind_handler = PagefindHandler.new(pagefind_path: pagefind_path, config: config)
     end
 
@@ -29,21 +31,20 @@ module Docyard
 
     private
 
-    attr_reader :docs_path, :file_watcher, :config, :router, :renderer, :asset_handler, :pagefind_handler
+    attr_reader :docs_path, :config, :router, :renderer, :asset_handler, :pagefind_handler, :dev_mode
 
     def handle_request(env)
       path = env["PATH_INFO"]
 
-      return handle_reload_check(env) if path == Constants::RELOAD_ENDPOINT
-      return asset_handler.serve_docyard_assets(path) if path.start_with?(Constants::DOCYARD_ASSETS_PREFIX)
       return pagefind_handler.serve(path) if path.start_with?(Constants::PAGEFIND_PREFIX)
+      return asset_handler.serve_docyard_assets(path) if path.start_with?(Constants::DOCYARD_ASSETS_PREFIX)
 
       public_response = asset_handler.serve_public_file(path)
       return public_response if public_response
 
       handle_documentation_request(path)
     rescue StandardError => e
-      handle_error(e)
+      handle_error(e, env)
     end
 
     def handle_documentation_request(path)
@@ -106,14 +107,20 @@ module Docyard
     end
 
     def build_navigation_html(template_resolver, current_path, markdown, header_ctas)
-      return { sidebar_html: "", prev_next_html: "", breadcrumbs: nil } unless template_resolver.show_sidebar?
+      navigation_builder.build(
+        current_path: current_path,
+        markdown: markdown,
+        header_ctas: header_ctas,
+        show_sidebar: template_resolver.show_sidebar?
+      )
+    end
 
-      sidebar_builder = build_sidebar_instance(current_path, header_ctas)
-      {
-        sidebar_html: sidebar_builder.to_html,
-        prev_next_html: build_prev_next(sidebar_builder, current_path, markdown),
-        breadcrumbs: build_breadcrumbs(sidebar_builder.tree, current_path)
-      }
+    def navigation_builder
+      @navigation_builder ||= Navigation::PageNavigationBuilder.new(
+        docs_path: docs_path,
+        config: config,
+        sidebar_cache: @sidebar_cache
+      )
     end
 
     def render_not_found_page
@@ -126,67 +133,28 @@ module Docyard
         docs_path: docs_path,
         current_path: current_path,
         config: config,
-        header_ctas: header_ctas
+        header_ctas: header_ctas,
+        sidebar_cache: @sidebar_cache
       )
     end
 
-    def build_prev_next(sidebar_builder, current_path, markdown)
-      PrevNextBuilder.new(
-        sidebar_tree: sidebar_builder.tree,
-        current_path: current_path,
-        frontmatter: markdown.frontmatter,
-        config: navigation_config
-      ).to_html
-    end
-
-    def build_breadcrumbs(sidebar_tree, current_path)
-      return nil unless breadcrumbs_enabled?
-
-      BreadcrumbBuilder.new(sidebar_tree: sidebar_tree, current_path: current_path)
-    end
-
-    def breadcrumbs_enabled?
-      config&.navigation&.breadcrumbs != false
-    end
-
-    def navigation_config
-      {}
-    end
-
     def branding_options
       BrandingResolver.new(config).resolve
     end
 
-    def handle_reload_check(env)
-      since = parse_since_timestamp(env)
-      reload_needed = file_watcher.changed_since?(since)
-
-      build_reload_response(reload_needed)
-    rescue StandardError => e
-      log_reload_error(e)
-      build_reload_response(false)
-    end
-
-    def parse_since_timestamp(env)
-      query = Rack::Utils.parse_query(env["QUERY_STRING"])
-      query["since"] ? Time.at(query["since"].to_f) : Time.now
-    end
-
-    def log_reload_error(error)
-      Docyard.logger.error "Reload check error: #{error.message}"
-      Docyard.logger.debug error.backtrace.join("\n")
-    end
-
-    def build_reload_response(reload_needed)
-      response_body = { reload: reload_needed, timestamp: Time.now.to_f }.to_json
-      [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_JSON }, [response_body]]
-    end
-
-    def handle_error(error)
-      Docyard.logger.error "Request error: #{error.message}"
-      Docyard.logger.debug error.backtrace.join("\n")
+    def handle_error(error, env)
+      request_context = build_request_context(env)
+      Docyard.logger.error("Request error: #{error.message} [#{request_context}]")
+      Docyard.logger.debug(error.backtrace.join("\n"))
       [Constants::STATUS_INTERNAL_ERROR, { "Content-Type" => Constants::CONTENT_TYPE_HTML },
        [renderer.render_server_error(error)]]
     end
+
+    def build_request_context(env)
+      method = env["REQUEST_METHOD"]
+      path = env["PATH_INFO"]
+      user_agent = env["HTTP_USER_AGENT"]&.slice(0, 50)
+      user_agent ? "#{method} #{path} - #{user_agent}" : "#{method} #{path}"
+    end
   end
 end

data/lib/docyard/server/router.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../utils/path_utils"
+
 module Docyard
   class Router
     attr_reader :docs_path
@@ -11,11 +13,11 @@ module Docyard
     def resolve(request_path)
       clean_path = sanitize_path(request_path)
 
-      file_path = File.join(docs_path, "#{clean_path}#{Constants::MARKDOWN_EXTENSION}")
-      return ResolutionResult.found(file_path) if File.file?(file_path)
+      file_path = safe_file_path("#{clean_path}#{Constants::MARKDOWN_EXTENSION}")
+      return ResolutionResult.found(file_path) if file_path && File.file?(file_path)
 
-      index_path = File.join(docs_path, clean_path, "#{Constants::INDEX_FILE}#{Constants::MARKDOWN_EXTENSION}")
-      return ResolutionResult.found(index_path) if File.file?(index_path)
+      index_path = safe_file_path(File.join(clean_path, "#{Constants::INDEX_FILE}#{Constants::MARKDOWN_EXTENSION}"))
+      return ResolutionResult.found(index_path) if index_path && File.file?(index_path)
 
       ResolutionResult.not_found
     end
@@ -23,9 +25,11 @@ module Docyard
     private
 
     def sanitize_path(request_path)
-      clean = request_path.delete_prefix("/").delete_suffix("/")
-      clean = Constants::INDEX_FILE if clean.empty?
-      clean.delete_suffix(Constants::MARKDOWN_EXTENSION)
+      Utils::PathUtils.sanitize_url_path(request_path)
+    end
+
+    def safe_file_path(relative_path)
+      Utils::PathUtils.resolve_safe_path(relative_path, docs_path)
     end
   end
 end

data/lib/docyard/server/sse_server.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+
+module Docyard
+  class SSEServer
+    HEARTBEAT_INTERVAL = 15
+    DEFAULT_PORT = 4201
+
+    def initialize(port: DEFAULT_PORT)
+      @port = port
+      @connections = []
+      @mutex = Mutex.new
+      @running = false
+      @server = nil
+      @accept_thread = nil
+      @heartbeat_thread = nil
+    end
+
+    attr_reader :port
+
+    def start
+      @running = true
+      @server = TCPServer.new("127.0.0.1", @port)
+      @server.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+
+      start_accept_thread
+      start_heartbeat_thread
+    end
+
+    def stop
+      @running = false
+      close_server
+      @accept_thread&.kill
+      @heartbeat_thread&.kill
+      close_all_connections
+    end
+
+    def broadcast(event_type, data = {})
+      message = format_sse_message(event_type, data)
+      dead_connections = []
+
+      @mutex.synchronize do
+        @connections.each do |conn|
+          write_to_connection(conn, message) or dead_connections << conn
+        end
+
+        dead_connections.each { |conn| remove_connection_unsafe(conn) }
+      end
+    end
+
+    def connection_count
+      @mutex.synchronize { @connections.size }
+    end
+
+    private
+
+    def close_server
+      @server&.close
+    rescue StandardError
+      nil
+    end
+
+    def start_accept_thread
+      @accept_thread = Thread.new do
+        while @running
+          begin
+            client = @server.accept
+            Thread.new { handle_new_connection(client) }
+          rescue IOError, Errno::EBADF
+            break unless @running
+          end
+        end
+      end
+    end
+
+    def handle_new_connection(client)
+      request = read_http_request(client)
+      return close_client(client) unless valid_sse_request?(request)
+
+      send_sse_headers(client)
+      @mutex.synchronize { @connections << client }
+    rescue StandardError
+      close_client(client)
+    end
+
+    def close_client(client)
+      client.close
+    rescue StandardError
+      nil
+    end
+
+    def read_http_request(client)
+      lines = []
+      while (line = client.gets)
+        break if line.strip.empty?
+
+        lines << line
+      end
+      lines.join
+    end
+
+    def valid_sse_request?(request)
+      request.include?("GET /_docyard/events") || request.include?("GET / ")
+    end
+
+    def send_sse_headers(client)
+      headers = [
+        "HTTP/1.1 200 OK",
+        "Content-Type: text/event-stream",
+        "Cache-Control: no-cache",
+        "Connection: keep-alive",
+        "Access-Control-Allow-Origin: *",
+        "",
+        ""
+      ].join("\r\n")
+
+      client.write(headers)
+      client.write("retry: 1000\n\n")
+      client.flush
+    end
+
+    def start_heartbeat_thread
+      @heartbeat_thread = Thread.new do
+        while @running
+          sleep HEARTBEAT_INTERVAL
+          broadcast("heartbeat", { time: Time.now.to_i }) if @running
+        end
+      end
+    end
+
+    def write_to_connection(conn, message)
+      conn.write_nonblock(message)
+      true
+    rescue IO::WaitWritable, IOError, Errno::EPIPE, Errno::ECONNRESET, Errno::ETIMEDOUT
+      false
+    end
+
+    def format_sse_message(event_type, data)
+      json_data = data.to_json
+      "event: #{event_type}\ndata: #{json_data}\n\n"
+    end
+
+    def remove_connection_unsafe(conn)
+      @connections.delete(conn)
+      close_client(conn)
+    end
+
+    def close_all_connections
+      @mutex.synchronize do
+        @connections.each { |conn| close_client(conn) }
+        @connections.clear
+      end
+    end
+  end
+end

data/lib/docyard/server/static_file_app.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rack/mime"
+
+module Docyard
+  class StaticFileApp
+    def initialize(root)
+      @root = root
+    end
+
+    def call(env)
+      path = env["PATH_INFO"]
+      file_path = File.join(@root, path)
+
+      if path.end_with?("/") || File.directory?(file_path)
+        index_path = File.join(file_path, "index.html")
+        return serve_file(index_path) if File.file?(index_path)
+      elsif File.file?(file_path)
+        return serve_file(file_path)
+      end
+
+      serve_not_found
+    end
+
+    private
+
+    def serve_file(path)
+      content = File.read(path)
+      content_type = Rack::Mime.mime_type(File.extname(path), "application/octet-stream")
+      [200, { "content-type" => content_type }, [content]]
+    end
+
+    def serve_not_found
+      error_page = File.join(@root, "404.html")
+      if File.file?(error_page)
+        [404, { "content-type" => "text/html; charset=utf-8" }, [File.read(error_page)]]
+      else
+        [404, { "content-type" => "text/plain" }, ["Not Found"]]
+      end
+    end
+  end
+end

data/lib/docyard/templates/assets/css/components/banner.css

@@ -53,6 +53,10 @@ body.has-announcement .secondary-header {
   top: calc(var(--header-height) + var(--tab-bar-height) + var(--announcement-height));
 }
 
+body.has-announcement:not(.has-tabs) .secondary-header {
+  top: calc(var(--header-height) + var(--announcement-height));
+}
+
 body.has-announcement .layout {
   padding-top: calc(var(--header-height) + var(--tab-bar-height) + var(--announcement-height));
 }
@@ -70,6 +74,33 @@ body.has-announcement:not(.has-tabs) .layout {
   padding-top: calc(var(--header-height) + var(--announcement-height));
 }
 
+@media (max-width: 1280px) and (min-width: 1025px) {
+  body.has-announcement .layout {
+    padding-top: calc(var(--header-height) + var(--tab-bar-height) + var(--announcement-height) + 3rem);
+  }
+
+  body.has-announcement:not(.has-tabs) .layout {
+    padding-top: calc(var(--header-height) + var(--announcement-height) + 3rem);
+  }
+}
+
+/* Mobile: tab bar is hidden, so don't include tab-bar-height */
+@media (max-width: 1024px) {
+  body.has-announcement .secondary-header {
+    top: calc(var(--header-height) + var(--announcement-height));
+  }
+
+  body.has-announcement .layout {
+    padding-top: calc(var(--header-height) + var(--announcement-height) + 3rem);
+  }
+
+  body.has-announcement .sidebar {
+    top: 0;
+    height: 100vh;
+    height: 100dvh;
+  }
+}
+
 .docyard-announcement__content {
   display: flex;
   align-items: center;

data/lib/docyard/templates/assets/css/components/breadcrumbs.css

@@ -40,7 +40,8 @@
   box-shadow: 0 0 0 var(--ring-width) oklch(from var(--ring) l c h / 50%);
 }
 
-.breadcrumb-toggle .docyard-icon {
+.breadcrumb-toggle .docyard-icon,
+.breadcrumb-toggle i[class*="ph-"] {
   width: 18px;
   height: 18px;
 }

data/lib/docyard/templates/assets/css/components/callout.css

@@ -15,16 +15,17 @@
 
 .docyard-callout__icon {
   flex-shrink: 0;
-  width: 1.25rem;
-  height: 1.25rem;
+  width: 1.5rem;
+  height: 1.5rem;
   display: flex;
   align-items: center;
   justify-content: center;
 }
 
-.docyard-callout__icon .docyard-icon {
-  width: 100%;
-  height: 100%;
+.docyard-callout__icon .docyard-icon,
+.docyard-callout__icon i[class*="ph-"] {
+  font-size: 1.25rem;
+  display: inline-block;
 }
 
 .docyard-callout__icon svg {
@@ -98,11 +99,30 @@
 }
 
 .docyard-callout__body :not(pre)>code {
-  background-color: oklch(from var(--input) l c h / 30%);
   padding: 0.125rem 0.375rem;
   border-radius: var(--radius-sm);
 }
 
+.docyard-callout--note .docyard-callout__body :not(pre)>code {
+  background-color: oklch(from var(--callout-note-border) l c h / 15%);
+}
+
+.docyard-callout--tip .docyard-callout__body :not(pre)>code {
+  background-color: oklch(from var(--callout-tip-border) l c h / 15%);
+}
+
+.docyard-callout--important .docyard-callout__body :not(pre)>code {
+  background-color: oklch(from var(--callout-important-border) l c h / 15%);
+}
+
+.docyard-callout--warning .docyard-callout__body :not(pre)>code {
+  background-color: oklch(from var(--callout-warning-border) l c h / 15%);
+}
+
+.docyard-callout--danger .docyard-callout__body :not(pre)>code {
+  background-color: oklch(from var(--callout-danger-border) l c h / 15%);
+}
+
 .docyard-callout--note {
   border-color: var(--callout-note-border);
   background-color: var(--callout-note-background);

data/lib/docyard/templates/assets/css/components/code-block.css

@@ -57,7 +57,8 @@
   flex-shrink: 0;
 }
 
-.docyard-code-block__icon .docyard-icon {
+.docyard-code-block__icon .docyard-icon,
+.docyard-code-block__icon i[class*="ph-"] {
   width: 1rem;
   height: 1rem;
   display: inline-flex;
@@ -468,7 +469,8 @@
     gap: var(--spacing-2);
   }
 
-  .docyard-code-block__icon .docyard-icon {
+  .docyard-code-block__icon .docyard-icon,
+  .docyard-code-block__icon i[class*="ph-"] {
     width: 0.875rem;
     height: 0.875rem;
   }

data/lib/docyard/templates/assets/css/components/code-group.css

@@ -44,7 +44,7 @@
 .docyard-code-group__tab {
   display: inline-flex;
   align-items: center;
-  justify-content: center;
+  justify-content: flex-start;
   gap: var(--spacing-1-5);
   padding: var(--spacing-2) var(--spacing-2-5);
   background: transparent;
@@ -60,9 +60,7 @@
   flex-shrink: 0;
   line-height: 1.5;
   outline: none;
-  max-width: 12rem;
-  overflow: hidden;
-  text-overflow: ellipsis;
+  max-width: 14rem;
 }
 
 .docyard-code-group__tab:hover {
@@ -79,7 +77,8 @@
   border-radius: var(--radius-sm);
 }
 
-.docyard-code-group__tab .docyard-icon {
+.docyard-code-group__tab .docyard-icon,
+.docyard-code-group__tab i[class*="ph-"] {
   width: 1rem;
   height: 1rem;
   display: inline-flex;
@@ -91,6 +90,13 @@
   height: 100%;
 }
 
+.docyard-code-group__tab-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  direction: rtl;
+  text-align: left;
+}
+
 .docyard-code-group__indicator {
   position: absolute;
   bottom: 0;
@@ -100,12 +106,18 @@
   border-radius: 1px;
   pointer-events: none;
   z-index: 1;
+  opacity: 0;
   transition:
     transform 0.4s cubic-bezier(0.34, 1.56, 0.64, 1),
-    width 0.3s cubic-bezier(0.34, 1.56, 0.64, 1);
+    width 0.3s cubic-bezier(0.34, 1.56, 0.64, 1),
+    opacity 0.15s ease;
   will-change: transform, width;
 }
 
+.docyard-code-group__indicator.is-ready {
+  opacity: 1;
+}
+
 .docyard-code-group__tabs-scroll-container.can-scroll-left .docyard-code-group__tabs {
   mask-image: linear-gradient(to right, transparent, black 2rem);
   -webkit-mask-image: linear-gradient(to right, transparent, black 2rem);
@@ -252,7 +264,8 @@
     gap: var(--spacing-1);
   }
 
-  .docyard-code-group__tab .docyard-icon {
+  .docyard-code-group__tab .docyard-icon,
+  .docyard-code-group__tab i[class*="ph-"] {
     width: 0.875rem;
     height: 0.875rem;
   }