docyard 0.7.0 → 0.9.0

data/lib/docyard/server/rack_application.rb

@@ -4,25 +4,23 @@ require "json"
 require "rack"
 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 "../rendering/template_resolver"
+require_relative "../routing/fallback_resolver"
+require_relative "pagefind_handler"
 
 module Docyard
   class RackApplication
-    PAGEFIND_CONTENT_TYPES = {
-      ".js" => "application/javascript; charset=utf-8",
-      ".css" => "text/css; charset=utf-8",
-      ".json" => "application/json; charset=utf-8"
-    }.freeze
-
     def initialize(docs_path:, file_watcher:, config: nil, pagefind_path: nil)
       @docs_path = docs_path
       @file_watcher = file_watcher
       @config = config
-      @pagefind_path = pagefind_path
       @router = Router.new(docs_path: docs_path)
-      @renderer = Renderer.new(base_url: config&.build&.base_url || "/", config: config)
+      @renderer = Renderer.new(base_url: config&.build&.base || "/", config: config)
       @asset_handler = AssetHandler.new
+      @pagefind_handler = PagefindHandler.new(pagefind_path: pagefind_path, config: config)
     end
 
     def call(env)
@@ -31,14 +29,17 @@ module Docyard
 
     private
 
-    attr_reader :docs_path, :file_watcher, :config, :pagefind_path, :router, :renderer, :asset_handler
+    attr_reader :docs_path, :file_watcher, :config, :router, :renderer, :asset_handler, :pagefind_handler
 
     def handle_request(env)
       path = env["PATH_INFO"]
 
       return handle_reload_check(env) if path == Constants::RELOAD_ENDPOINT
-      return asset_handler.serve(path) if path.start_with?(Constants::ASSETS_PREFIX)
-      return serve_pagefind(path) if path.start_with?(Constants::PAGEFIND_PREFIX)
+      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)
+
+      public_response = asset_handler.serve_public_file(path)
+      return public_response if public_response
 
       handle_documentation_request(path)
     rescue StandardError => e
@@ -46,45 +47,90 @@ module Docyard
     end
 
     def handle_documentation_request(path)
+      if root_path?(path)
+        html_response = serve_custom_landing_page
+        return html_response if html_response
+      end
+
       result = router.resolve(path)
 
       if result.found?
         render_documentation_page(result.file_path, path)
+      else
+        try_fallback_redirect(path)
+      end
+    end
+
+    def root_path?(path)
+      path == "/" || path.empty?
+    end
+
+    def serve_custom_landing_page
+      html_path = File.join(docs_path, "index.html")
+      return nil unless File.file?(html_path)
+
+      html = File.read(html_path)
+      [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
+    end
+
+    def try_fallback_redirect(path)
+      sidebar_builder = build_sidebar_instance(path)
+      fallback_resolver = Routing::FallbackResolver.new(
+        docs_path: docs_path,
+        sidebar_builder: sidebar_builder
+      )
+
+      fallback_path = fallback_resolver.resolve_fallback(path)
+      if fallback_path
+        redirect_to(fallback_path)
       else
         render_not_found_page
       end
     end
 
+    def redirect_to(path)
+      [Constants::STATUS_REDIRECT, { "Location" => path }, []]
+    end
+
     def render_documentation_page(file_path, current_path)
-      sidebar_builder = build_sidebar_instance(current_path)
+      markdown = Markdown.new(File.read(file_path))
+      template_resolver = TemplateResolver.new(markdown.frontmatter, @config&.data)
+      branding = branding_options
 
-      html = renderer.render_file(
-        file_path,
-        sidebar_html: sidebar_builder.to_html,
-        prev_next_html: build_prev_next(sidebar_builder, current_path, file_path),
-        branding: branding_options
-      )
+      navigation = build_navigation_html(template_resolver, current_path, markdown, branding[:header_ctas])
+      html = renderer.render_file(file_path, **navigation, branding: branding,
+                                                           template_options: template_resolver.to_options,
+                                                           current_path: current_path)
 
       [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
     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?
+
+      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)
+      }
+    end
+
     def render_not_found_page
       html = renderer.render_not_found
       [Constants::STATUS_NOT_FOUND, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
     end
 
-    def build_sidebar_instance(current_path)
+    def build_sidebar_instance(current_path, header_ctas = [])
       SidebarBuilder.new(
         docs_path: docs_path,
         current_path: current_path,
-        config: config
+        config: config,
+        header_ctas: header_ctas
       )
     end
 
-    def build_prev_next(sidebar_builder, current_path, file_path)
-      markdown_content = File.read(file_path)
-      markdown = Markdown.new(markdown_content)
-
+    def build_prev_next(sidebar_builder, current_path, markdown)
       PrevNextBuilder.new(
         sidebar_tree: sidebar_builder.tree,
         current_path: current_path,
@@ -93,10 +139,18 @@ module Docyard
       ).to_html
     end
 
-    def navigation_config
-      return {} unless config
+    def build_breadcrumbs(sidebar_tree, current_path)
+      return nil unless breadcrumbs_enabled?
+
+      BreadcrumbBuilder.new(sidebar_tree: sidebar_tree, current_path: current_path)
+    end
 
-      config.navigation&.footer || {}
+    def breadcrumbs_enabled?
+      config&.navigation&.breadcrumbs != false
+    end
+
+    def navigation_config
+      {}
     end
 
     def branding_options
@@ -134,42 +188,5 @@ module Docyard
       [Constants::STATUS_INTERNAL_ERROR, { "Content-Type" => Constants::CONTENT_TYPE_HTML },
        [renderer.render_server_error(error)]]
     end
-
-    def serve_pagefind(path)
-      relative_path = path.delete_prefix(Constants::PAGEFIND_PREFIX)
-      return pagefind_not_found if relative_path.include?("..")
-
-      file_path = resolve_pagefind_file(relative_path)
-      return pagefind_not_found unless file_path && File.file?(file_path)
-
-      content = File.binread(file_path)
-      content_type = pagefind_content_type(file_path)
-
-      headers = {
-        "Content-Type" => content_type,
-        "Cache-Control" => "no-cache, no-store, must-revalidate",
-        "Pragma" => "no-cache",
-        "Expires" => "0"
-      }
-
-      [Constants::STATUS_OK, headers, [content]]
-    end
-
-    def resolve_pagefind_file(relative_path)
-      return File.join(pagefind_path, relative_path) if pagefind_path && Dir.exist?(pagefind_path)
-
-      output_dir = config&.build&.output_dir || "dist"
-      File.join(output_dir, "pagefind", relative_path)
-    end
-
-    def pagefind_content_type(file_path)
-      extension = File.extname(file_path)
-      PAGEFIND_CONTENT_TYPES.fetch(extension, "application/octet-stream")
-    end
-
-    def pagefind_not_found
-      message = "Pagefind not found. Run 'docyard build' first."
-      [Constants::STATUS_NOT_FOUND, { "Content-Type" => "text/plain" }, [message]]
-    end
   end
 end

data/lib/docyard/templates/assets/css/code.css

@@ -1,32 +1,27 @@
-/* Code Block Styles */
-
-/* Code blocks */
 .content pre {
-  margin: var(--space-6) 0;
-  border-radius: var(--radius-lg);
+  margin: var(--spacing-6) 0;
+  border-radius: var(--radius-2xl);
   overflow-x: auto;
-  border: 1px solid var(--color-border);
-  box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.03);
+  overscroll-behavior-x: contain;
 }
 
 .content pre code {
   display: block;
-  padding: var(--space-4);
+  padding: var(--spacing-4);
   font-family: var(--font-mono);
-  font-size: var(--font-size-sm);
-  line-height: var(--line-height-relaxed);
-  background-color: var(--color-code-bg);
-  color: var(--color-code-text);
+  font-size: var(--text-sm);
+  line-height: var(--leading-relaxed);
+  background-color: oklch(from var(--input) l c h / 30%);
+  color: var(--code-foreground);
   overflow-x: auto;
+  overscroll-behavior-x: contain;
 }
 
-/* Syntax highlighting - GitHub style */
 .highlight {
-  margin: var(--space-6) 0;
-  background-color: var(--color-code-bg);
-  border-radius: var(--radius-lg);
-  border: 1px solid var(--color-border);
-  box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.03);
+  margin: var(--spacing-6) 0;
+  background-color: oklch(from var(--input) l c h / 30%);
+  border-radius: var(--radius-2xl);
+  border: 1px solid var(--input);
 }
 
 .highlight pre {
@@ -44,7 +39,7 @@
 
 .highlight {
   color: #24292f;
-  background-color: #f6f8fa;
+  background-color: oklch(from var(--input) l c h / 30%);
 }
 
 .highlight .w {
@@ -52,7 +47,6 @@
   background-color: transparent;
 }
 
-/* Keywords */
 .highlight .k,
 .highlight .kd,
 .highlight .kn,
@@ -72,7 +66,6 @@
   background-color: #ffebe9;
 }
 
-/* Built-in names */
 .highlight .nb,
 .highlight .nc,
 .highlight .no,
@@ -80,7 +73,6 @@
   color: #953800;
 }
 
-/* Strings and regex */
 .highlight .sr,
 .highlight .na,
 .highlight .nt {
@@ -97,7 +89,6 @@
   font-style: italic;
 }
 
-/* Constants and literals */
 .highlight .kc,
 .highlight .l,
 .highlight .ld,
@@ -117,7 +108,6 @@
   color: #0550ae;
 }
 
-/* Variables */
 .highlight .nv,
 .highlight .vc,
 .highlight .vg,
@@ -126,20 +116,17 @@
   color: #0550ae;
 }
 
-/* Operators */
 .highlight .o,
 .highlight .ow {
   color: #0550ae;
 }
 
-/* Headers and subheaders in diffs */
 .highlight .gh,
 .highlight .gu {
   color: #0550ae;
   font-weight: bold;
 }
 
-/* Strings */
 .highlight .s,
 .highlight .sa,
 .highlight .sc,
@@ -154,20 +141,17 @@
   color: #0a3069;
 }
 
-/* Decorators and functions */
 .highlight .nd,
 .highlight .nf,
 .highlight .fm {
   color: #8250df;
 }
 
-/* Errors */
 .highlight .err {
   color: #f6f8fa;
   background-color: #82071e;
 }
 
-/* Comments */
 .highlight .c,
 .highlight .ch,
 .highlight .cd,
@@ -181,13 +165,11 @@
   color: #6e7781;
 }
 
-/* Name indicators */
 .highlight .ni,
 .highlight .si {
   color: #24292f;
 }
 
-/* Generic emphasis */
 .highlight .ge {
   color: #24292f;
   font-style: italic;
@@ -198,29 +180,27 @@
   font-weight: bold;
 }
 
-/* Code block scrollbar */
 .content pre::-webkit-scrollbar {
   height: 0.5rem;
 }
 
 .content pre::-webkit-scrollbar-track {
-  background: var(--color-bg-secondary);
+  background: var(--secondary);
   border-radius: var(--radius-md);
 }
 
 .content pre::-webkit-scrollbar-thumb {
-  background: var(--color-border);
+  background: var(--border);
   border-radius: var(--radius-md);
 }
 
 .content pre::-webkit-scrollbar-thumb:hover {
-  background: var(--color-text-tertiary);
+  background: var(--muted-foreground);
 }
 
-/* Dark Mode Syntax Highlighting - GitHub Dark */
 .dark .highlight {
   color: #e6edf3;
-  background-color: #161b22;
+  background-color: oklch(from var(--input) l c h / 30%);
 }
 
 .dark .highlight .w {
@@ -228,7 +208,6 @@
   background-color: transparent;
 }
 
-/* Keywords */
 .dark .highlight .k,
 .dark .highlight .kd,
 .dark .highlight .kn,
@@ -248,7 +227,6 @@
   background-color: #490202;
 }
 
-/* Built-in names */
 .dark .highlight .nb,
 .dark .highlight .nc,
 .dark .highlight .no,
@@ -256,7 +234,6 @@
   color: #ffa657;
 }
 
-/* Strings and regex */
 .dark .highlight .sr,
 .dark .highlight .na,
 .dark .highlight .nt {
@@ -268,7 +245,6 @@
   background-color: #0f3b17;
 }
 
-/* Constants and literals */
 .dark .highlight .kc,
 .dark .highlight .l,
 .dark .highlight .ld,
@@ -288,7 +264,6 @@
   color: #79c0ff;
 }
 
-/* Variables */
 .dark .highlight .nv,
 .dark .highlight .vc,
 .dark .highlight .vg,
@@ -297,20 +272,17 @@
   color: #79c0ff;
 }
 
-/* Operators */
 .dark .highlight .o,
 .dark .highlight .ow {
   color: #79c0ff;
 }
 
-/* Headers and subheaders in diffs */
 .dark .highlight .gh,
 .dark .highlight .gu {
   color: #79c0ff;
   font-weight: bold;
 }
 
-/* Strings */
 .dark .highlight .s,
 .dark .highlight .sa,
 .dark .highlight .sc,
@@ -325,20 +297,17 @@
   color: #a5d6ff;
 }
 
-/* Decorators and functions */
 .dark .highlight .nd,
 .dark .highlight .nf,
 .dark .highlight .fm {
   color: #d2a8ff;
 }
 
-/* Errors */
 .dark .highlight .err {
   color: #161b22;
   background-color: #ffa198;
 }
 
-/* Comments */
 .dark .highlight .c,
 .dark .highlight .ch,
 .dark .highlight .cd,
@@ -352,13 +321,11 @@
   color: #8b949e;
 }
 
-/* Name indicators */
 .dark .highlight .ni,
 .dark .highlight .si {
   color: #e6edf3;
 }
 
-/* Generic emphasis */
 .dark .highlight .ge {
   color: #e6edf3;
   font-style: italic;

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

@@ -0,0 +1,86 @@
+.docyard-abbr {
+  text-decoration: underline;
+  text-decoration-style: dotted;
+  text-decoration-color: var(--muted-foreground);
+  text-underline-offset: 3px;
+  cursor: help;
+  position: relative;
+}
+
+.docyard-abbr:hover {
+  text-decoration-color: var(--primary);
+}
+
+.docyard-abbr-popover {
+  position: absolute;
+  z-index: 1000;
+  width: max-content;
+  max-width: 280px;
+  padding: var(--spacing-3) var(--spacing-4);
+  background: var(--background);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  box-shadow:
+    0 4px 6px -1px oklch(from var(--foreground) l c h / 8%),
+    0 2px 4px -2px oklch(from var(--foreground) l c h / 6%);
+  pointer-events: none;
+  opacity: 0;
+  transform: translateY(-4px) scale(0.96);
+  transition:
+    opacity 0.15s ease,
+    transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+
+.docyard-abbr-popover.is-visible {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+}
+
+.docyard-abbr-popover::after {
+  content: "";
+  position: absolute;
+  bottom: -6px;
+  left: var(--arrow-left, 16px);
+  width: 10px;
+  height: 10px;
+  background: var(--background);
+  border-bottom: 1px solid var(--border);
+  border-right: 1px solid var(--border);
+  transform: rotate(45deg);
+}
+
+.docyard-abbr-popover.is-below::after {
+  top: -6px;
+  bottom: auto;
+  border-bottom: none;
+  border-right: none;
+  border-top: 1px solid var(--border);
+  border-left: 1px solid var(--border);
+}
+
+.docyard-abbr-popover__term {
+  display: block;
+  font-weight: var(--font-semibold);
+  font-size: var(--text-sm);
+  color: var(--foreground);
+  margin-bottom: var(--spacing-1);
+}
+
+.docyard-abbr-popover__definition {
+  display: block;
+  font-size: var(--text-sm);
+  color: var(--muted-foreground);
+  line-height: var(--leading-relaxed);
+}
+
+@media (max-width: 640px) {
+  .docyard-abbr-popover {
+    max-width: 240px;
+    padding: var(--spacing-2) var(--spacing-3);
+  }
+
+  .docyard-abbr-popover__term,
+  .docyard-abbr-popover__definition {
+    font-size: var(--text-xs);
+  }
+}

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

@@ -0,0 +1,138 @@
+.docyard-accordion {
+  margin: var(--spacing-4) 0;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-xl);
+  background-color: var(--card);
+}
+
+.docyard-accordion__summary {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-3);
+  padding: var(--spacing-3) var(--spacing-4);
+  cursor: pointer;
+  user-select: none;
+  font-weight: var(--font-medium);
+  font-size: var(--text-sm);
+  color: var(--foreground);
+  list-style: none;
+  transition: background-color var(--transition-fast);
+  border-radius: var(--radius-xl);
+}
+
+.docyard-accordion__summary::-webkit-details-marker {
+  display: none;
+}
+
+.docyard-accordion__summary::marker {
+  display: none;
+  content: "";
+}
+
+.docyard-accordion__summary:hover {
+  background-color: var(--accent);
+}
+
+.docyard-accordion__summary:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: -2px;
+}
+
+.docyard-accordion[open] .docyard-accordion__summary {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+.docyard-accordion__icon {
+  flex-shrink: 0;
+  width: 1rem;
+  height: 1rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--muted-foreground);
+  transition: transform var(--transition-fast);
+}
+
+.docyard-accordion__icon svg {
+  width: 100%;
+  height: 100%;
+}
+
+.docyard-accordion[open] .docyard-accordion__icon {
+  transform: rotate(90deg);
+}
+
+.docyard-accordion__title {
+  flex: 1;
+}
+
+.docyard-accordion__content {
+  padding: var(--spacing-4);
+  font-size: var(--text-sm);
+  color: var(--foreground);
+  line-height: var(--leading-relaxed);
+  border-top: 1px solid var(--border);
+}
+
+.docyard-accordion__content > *:first-child {
+  margin-top: 0;
+}
+
+.docyard-accordion__content > *:last-child {
+  margin-bottom: 0;
+}
+
+.docyard-accordion__content a {
+  color: var(--primary);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
+.docyard-accordion__content a:hover {
+  color: var(--foreground);
+}
+
+.docyard-accordion__content pre {
+  margin: var(--spacing-4) 0;
+  border-radius: var(--radius-lg);
+}
+
+.docyard-accordion__content :not(pre) > code {
+  background-color: var(--muted);
+  padding: 0.125rem 0.375rem;
+  border-radius: var(--radius-sm);
+  font-size: 0.875em;
+}
+
+.docyard-accordion + .docyard-accordion {
+  margin-top: -1px;
+  border-top-left-radius: 0;
+  border-top-right-radius: 0;
+}
+
+.docyard-accordion + .docyard-accordion .docyard-accordion__summary {
+  border-top-left-radius: 0;
+  border-top-right-radius: 0;
+}
+
+.docyard-accordion:has(+ .docyard-accordion) {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+  margin-bottom: 0;
+}
+
+.docyard-accordion:has(+ .docyard-accordion) .docyard-accordion__summary {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docyard-accordion__icon {
+    transition: none;
+  }
+
+  .docyard-accordion__summary {
+    transition: none;
+  }
+}