docyard 1.2.0 → 1.4.0

data/lib/docyard/deploy/adapters/github_pages.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require_relative "base"
+
+module Docyard
+  module Deploy
+    module Adapters
+      class GithubPages < Base
+        def platform_name
+          "GitHub Pages"
+        end
+
+        private
+
+        def cli_name
+          "gh"
+        end
+
+        def cli_install_hint
+          "https://cli.github.com"
+        end
+
+        def run_deploy
+          remote_url = fetch_remote_url
+          Dir.mktmpdir do |tmp|
+            prepare_deploy_dir(tmp)
+            push_to_gh_pages(tmp, remote_url)
+          end
+          build_pages_url(remote_url)
+        end
+
+        def fetch_remote_url
+          execute_command("git", "remote", "get-url", "origin").strip
+        end
+
+        def prepare_deploy_dir(tmp)
+          FileUtils.cp_r("#{output_dir}/.", tmp)
+          execute_command("git", "-C", tmp, "init", "-b", "gh-pages")
+          execute_command("git", "-C", tmp, "add", ".")
+          execute_command("git", "-C", tmp, "commit", "-m", "Deploy via docyard")
+        end
+
+        def push_to_gh_pages(tmp, remote_url)
+          execute_command("git", "-C", tmp, "remote", "add", "origin", remote_url)
+          execute_command("git", "-C", tmp, "push", "--force", "origin", "gh-pages")
+        end
+
+        def build_pages_url(remote_url)
+          match = remote_url.match(%r{github\.com[:/]([^/]+)/([^/.]+)})
+          return nil unless match
+
+          owner, repo = match.captures
+          "https://#{owner}.github.io/#{repo}/"
+        end
+      end
+    end
+  end
+end

data/lib/docyard/deploy/adapters/netlify.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Docyard
+  module Deploy
+    module Adapters
+      class Netlify < Base
+        def platform_name
+          "Netlify"
+        end
+
+        private
+
+        def cli_name
+          "netlify"
+        end
+
+        def cli_install_hint
+          "npm i -g netlify-cli"
+        end
+
+        def run_deploy
+          args = ["netlify", "deploy", "--dir=#{output_dir}"]
+          args << "--prod" if production
+          output = execute_command(*args)
+          extract_url(output)
+        end
+
+        def extract_url(output)
+          pattern = production ? /Website URL:\s+(\S+)/ : /Website draft URL:\s+(\S+)/
+          output.match(pattern)&.captures&.first
+        end
+      end
+    end
+  end
+end

data/lib/docyard/deploy/adapters/vercel.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Docyard
+  module Deploy
+    module Adapters
+      class Vercel < Base
+        def platform_name
+          "Vercel"
+        end
+
+        private
+
+        def cli_name
+          "vercel"
+        end
+
+        def cli_install_hint
+          "npm i -g vercel"
+        end
+
+        def run_deploy
+          args = ["vercel", output_dir, "--yes"]
+          args << "--prod" if production
+          output = execute_command(*args)
+          extract_url(output)
+        end
+
+        def extract_url(output)
+          output.strip.lines.last&.strip
+        end
+      end
+    end
+  end
+end

data/lib/docyard/deploy/deployer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "platform_detector"
+require_relative "adapters/vercel"
+require_relative "adapters/netlify"
+require_relative "adapters/cloudflare"
+require_relative "adapters/github_pages"
+
+module Docyard
+  module Deploy
+    class Deployer
+      ADAPTERS = {
+        "vercel" => Adapters::Vercel,
+        "netlify" => Adapters::Netlify,
+        "cloudflare" => Adapters::Cloudflare,
+        "github-pages" => Adapters::GithubPages
+      }.freeze
+
+      attr_reader :config, :platform, :production, :skip_build
+
+      def initialize(to: nil, production: true, skip_build: false)
+        @config = Config.new
+        @platform = to
+        @production = production
+        @skip_build = skip_build
+      end
+
+      def deploy
+        print_header
+        ensure_build
+        adapter = resolve_adapter
+        print_deploy_info(adapter)
+        url = adapter.deploy
+        print_success(url)
+        true
+      rescue DeployError => e
+        print_error(e)
+        false
+      end
+
+      private
+
+      def print_header
+        puts
+        puts "  #{UI.bold('Docyard')} v#{VERSION}"
+        puts "  Deploying..."
+        puts
+      end
+
+      def ensure_build
+        return if skip_build
+
+        require_relative "../builder"
+        builder = Builder.new
+        raise DeployError, "Build failed" unless builder.build
+      end
+
+      def resolve_adapter
+        name = platform || detect_platform
+        adapter_class = ADAPTERS[name]
+        raise DeployError, "Unknown platform: #{name}. Valid options: #{ADAPTERS.keys.join(', ')}" unless adapter_class
+
+        adapter_class.new(output_dir: config.build.output, production: production, config: config)
+      end
+
+      def detect_platform
+        detected = PlatformDetector.new.detect
+        return detected if detected
+
+        raise DeployError,
+              "Could not detect platform. Use --to to specify one: #{ADAPTERS.keys.join(', ')}"
+      end
+
+      def print_deploy_info(adapter)
+        environment = production ? "production" : "preview"
+        puts "  #{UI.dim('Platform')}        #{adapter.platform_name}"
+        puts "  #{UI.dim('Environment')}     #{environment}"
+        puts "  #{UI.dim('Directory')}       #{config.build.output}/"
+        puts
+      end
+
+      def print_success(url)
+        puts "  #{UI.success('Deployed successfully')}"
+        puts "  #{url}" if url
+        puts
+      end
+
+      def print_error(error)
+        puts "  #{UI.error('Deploy failed')}"
+        puts "  #{error.message}"
+        puts
+      end
+    end
+  end
+end

data/lib/docyard/deploy/platform_detector.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Deploy
+    class PlatformDetector
+      DETECTION_RULES = [
+        { files: ["vercel.json"], dirs: [".vercel"], platform: "vercel" },
+        { files: ["netlify.toml"], dirs: [".netlify"], platform: "netlify" },
+        { files: ["wrangler.toml", "wrangler.jsonc"], dirs: [], platform: "cloudflare" },
+        { files: [], dirs: [".github/workflows"], platform: "github-pages" }
+      ].freeze
+
+      def initialize(project_root = Dir.pwd)
+        @project_root = project_root
+      end
+
+      def detect
+        DETECTION_RULES.each do |rule|
+          return rule[:platform] if matches?(rule)
+        end
+        nil
+      end
+
+      private
+
+      def matches?(rule)
+        rule[:files].any? { |f| File.exist?(File.join(@project_root, f)) } ||
+          rule[:dirs].any? { |d| Dir.exist?(File.join(@project_root, d)) }
+      end
+    end
+  end
+end

data/lib/docyard/errors.rb

@@ -8,4 +8,6 @@ module Docyard
   class SidebarConfigError < Error; end
 
   class BuildError < Error; end
+
+  class DeployError < Error; end
 end

data/lib/docyard/rendering/markdown.rb

@@ -19,6 +19,7 @@ require_relative "../components/processors/include_processor"
 require_relative "../components/processors/code_block_options_preprocessor"
 require_relative "../components/processors/code_block_diff_preprocessor"
 require_relative "../components/processors/code_block_focus_preprocessor"
+require_relative "../components/processors/code_block_annotation_preprocessor"
 require_relative "../components/processors/code_block_extended_fence_preprocessor"
 require_relative "../components/processors/code_block_extended_fence_postprocessor"
 require_relative "../components/processors/table_wrapper_processor"
@@ -29,6 +30,7 @@ require_relative "../components/processors/video_embed_processor"
 require_relative "../components/processors/file_tree_processor"
 require_relative "../components/processors/abbreviation_processor"
 require_relative "../components/processors/tooltip_processor"
+require_relative "../components/processors/variables_processor"
 require_relative "../components/processors/table_of_contents_processor"
 require_relative "../components/aliases"
 

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

@@ -0,0 +1,265 @@
+.docyard-code-annotation {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--code-annotation-size);
+  height: var(--code-annotation-size);
+  margin-left: var(--spacing-1);
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-4xl);
+  background: none;
+  color: var(--primary);
+  cursor: pointer;
+  vertical-align: middle;
+  opacity: 0.7;
+  transition: opacity 150ms ease, transform 150ms ease;
+}
+
+.docyard-code-annotation::before {
+  content: "";
+  position: absolute;
+  inset: -0.375em;
+}
+
+.docyard-code-annotation i[class*="ph-"] {
+  font-size: 1.25em;
+  vertical-align: 0;
+}
+
+@media (hover: hover) {
+  .docyard-code-annotation:hover {
+    opacity: 1;
+  }
+}
+
+.docyard-code-annotation:active {
+  transform: scale(0.92);
+}
+
+.docyard-code-annotation.is-active {
+  opacity: 1;
+}
+
+.docyard-code-annotation:focus-visible {
+  opacity: 1;
+  outline: 1.5px solid var(--primary);
+  outline-offset: 1px;
+  border-radius: 2px;
+}
+
+.docyard-code-block--has-annotations .docyard-code-line {
+  padding-right: calc(var(--code-annotation-size) + var(--spacing-1));
+}
+
+.docyard-code-annotation-popover {
+  position: absolute;
+  z-index: var(--z-tooltip);
+  width: max-content;
+  max-width: 24rem;
+  max-height: 20rem;
+  overflow-y: auto;
+  padding: var(--spacing-3) var(--spacing-4);
+  background: var(--popover);
+  color: oklch(from var(--popover-foreground) l c h / 85%);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  box-shadow:
+    0 1px 2px oklch(from var(--foreground) l c h / 3%),
+    0 4px 12px oklch(from var(--foreground) l c h / 6%),
+    0 16px 32px -8px oklch(from var(--foreground) l c h / 8%);
+  pointer-events: none;
+  opacity: 0;
+  transform: translateY(4px) scale(0.96);
+  transform-origin: var(--arrow-left, 16px) top;
+  transition:
+    opacity 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    transform 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94);
+}
+
+.docyard-code-annotation-popover.is-visible {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+  pointer-events: auto;
+  transition:
+    opacity 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    transform 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94);
+}
+
+.docyard-code-annotation-popover.is-above {
+  transform: translateY(-4px) scale(0.96);
+  transform-origin: var(--arrow-left, 16px) bottom;
+}
+
+.docyard-code-annotation-popover.is-above.is-visible {
+  transform: translateY(0) scale(1);
+}
+
+.docyard-code-annotation-popover::after {
+  content: "";
+  position: absolute;
+  top: -5px;
+  left: var(--arrow-left, 16px);
+  width: 9px;
+  height: 9px;
+  background: var(--popover);
+  border-top: 1px solid var(--border);
+  border-left: 1px solid var(--border);
+  border-radius: 1px 0 0 0;
+  transform: rotate(45deg);
+}
+
+.docyard-code-annotation-popover.is-above::after {
+  top: auto;
+  bottom: -5px;
+  border-top: none;
+  border-left: none;
+  border-bottom: 1px solid var(--border);
+  border-right: 1px solid var(--border);
+}
+
+.docyard-code-annotation-popover p {
+  margin: 0;
+  font-size: var(--text-sm);
+  line-height: var(--leading-relaxed);
+}
+
+.docyard-code-annotation-popover * + p,
+.docyard-code-annotation-popover * + ul,
+.docyard-code-annotation-popover * + ol,
+.docyard-code-annotation-popover * + blockquote {
+  margin-top: var(--spacing-2);
+}
+
+.docyard-code-annotation-popover * + .table-wrapper,
+.docyard-code-annotation-popover * + table {
+  margin-top: var(--spacing-2);
+}
+
+.docyard-code-annotation-popover ul,
+.docyard-code-annotation-popover ol {
+  margin: 0;
+  padding-left: var(--spacing-6);
+}
+
+.docyard-code-annotation-popover ul {
+  list-style-type: disc;
+}
+
+.docyard-code-annotation-popover ol {
+  list-style-type: decimal;
+}
+
+.docyard-code-annotation-popover li {
+  margin: var(--spacing-1) 0;
+  padding-left: var(--spacing-1);
+  font-size: var(--text-sm);
+  line-height: var(--leading-relaxed);
+}
+
+.docyard-code-annotation-popover li::marker {
+  color: var(--muted-foreground);
+}
+
+.docyard-code-annotation-popover table {
+  width: 100%;
+  border-spacing: 0;
+  border-collapse: separate;
+  font-size: var(--text-sm);
+  margin: 0;
+  border: 1px solid var(--table-border);
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+}
+
+.docyard-code-annotation-popover thead {
+  background-color: var(--table-header-bg);
+}
+
+.docyard-code-annotation-popover th {
+  padding: var(--spacing-2) var(--spacing-3);
+  text-align: left;
+  font-weight: var(--font-semibold);
+  font-size: var(--text-xs);
+  color: var(--popover-foreground);
+  vertical-align: middle;
+}
+
+.docyard-code-annotation-popover td {
+  padding: var(--spacing-2) var(--spacing-3);
+  font-size: var(--text-xs);
+  vertical-align: middle;
+  border-top: 1px solid var(--table-row-border);
+}
+
+.docyard-code-annotation-popover blockquote {
+  margin: 0;
+  padding-left: var(--spacing-6);
+  border-left: 4px solid var(--border);
+  color: var(--muted-foreground);
+}
+
+.docyard-code-annotation-popover blockquote p {
+  margin: var(--spacing-1) 0;
+}
+
+.docyard-code-annotation-popover code {
+  padding: 0.125rem 0.5rem;
+  background-color: oklch(from var(--muted) l c h / 80%);
+  color: var(--popover-foreground);
+  border-radius: var(--radius-sm);
+  font-size: 0.875em;
+  font-weight: var(--font-medium);
+  font-variant-ligatures: none;
+}
+
+.docyard-code-annotation-popover strong {
+  font-weight: var(--font-semibold);
+  color: var(--popover-foreground);
+}
+
+.docyard-code-annotation-popover a {
+  color: var(--popover-foreground);
+  font-weight: var(--font-semibold);
+  text-decoration: none;
+  border-bottom: 1px solid oklch(from var(--primary) l c h / 40%);
+  transition: border-bottom var(--transition-fast);
+}
+
+.docyard-code-annotation-popover a:hover {
+  border-bottom: 2px solid var(--primary);
+}
+
+@media (max-width: 640px) {
+  .docyard-code-annotation-popover {
+    max-width: 16rem;
+    padding: var(--spacing-2-5) var(--spacing-3);
+  }
+
+  .docyard-code-annotation-popover p,
+  .docyard-code-annotation-popover li {
+    font-size: var(--text-xs);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docyard-code-annotation,
+  .docyard-code-annotation-popover {
+    transition: none;
+  }
+
+  .docyard-code-annotation:active {
+    transform: none;
+  }
+
+  .docyard-code-annotation-popover,
+  .docyard-code-annotation-popover.is-above {
+    transform: none;
+  }
+
+  .docyard-code-annotation-popover.is-visible,
+  .docyard-code-annotation-popover.is-above.is-visible {
+    transform: none;
+  }
+}

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

@@ -84,6 +84,8 @@
   --callout-danger-background: rgba(254, 242, 242, 0.5);
   --callout-danger-border: rgba(239, 68, 68, 0.2);
 
+  --code-annotation-size: 1.25em;
+
   --code-block-bg: oklab(0 0 0 / 0.03);
   --code-block-border: oklab(0 0 0 / 0.06);
   --code-block-header-bg: oklab(0 0 0 / 0.02);

data/lib/docyard/templates/assets/js/components/code-annotation.js

@@ -0,0 +1,136 @@
+var annotationPopover = null;
+var activeAnnotationButton = null;
+
+function initCodeAnnotations(root) {
+  if (typeof root === 'undefined') root = document;
+  var buttons = root.querySelectorAll('.docyard-code-annotation');
+  if (buttons.length === 0) return;
+
+  if (!annotationPopover) {
+    annotationPopover = document.createElement('div');
+    annotationPopover.className = 'docyard-code-annotation-popover';
+    document.body.appendChild(annotationPopover);
+
+    document.addEventListener('click', function(e) {
+      if (activeAnnotationButton &&
+          !annotationPopover.contains(e.target) &&
+          !e.target.closest('.docyard-code-annotation')) {
+        hideAnnotationPopover();
+      }
+    });
+
+    document.addEventListener('keydown', function(e) {
+      if (e.key === 'Escape' && activeAnnotationButton) {
+        hideAnnotationPopover();
+        activeAnnotationButton.focus();
+      }
+    });
+  }
+
+  buttons.forEach(function(button) {
+    if (button.hasAttribute('data-annotation-initialized')) return;
+    button.setAttribute('data-annotation-initialized', 'true');
+
+    button.addEventListener('click', function(e) {
+      e.stopPropagation();
+      if (activeAnnotationButton === button) {
+        hideAnnotationPopover();
+      } else {
+        showAnnotationPopover(button);
+      }
+    });
+  });
+}
+
+function setAnnotationIcon(button, name, animate) {
+  var icon = button.querySelector('i[class*="ph-"]');
+  if (!icon) return;
+  if (!animate) {
+    icon.className = 'ph ph-' + name;
+    return;
+  }
+  icon.style.transition = 'opacity 100ms ease, transform 100ms ease';
+  icon.style.opacity = '0';
+  icon.style.transform = 'scale(0.5)';
+  setTimeout(function() {
+    icon.className = 'ph ph-' + name;
+    icon.style.opacity = '1';
+    icon.style.transform = 'scale(1)';
+  }, 100);
+}
+
+function showAnnotationPopover(button) {
+  if (activeAnnotationButton) {
+    setAnnotationIcon(activeAnnotationButton, 'plus-circle', true);
+    activeAnnotationButton.classList.remove('is-active');
+  }
+
+  activeAnnotationButton = button;
+  button.classList.add('is-active');
+  setAnnotationIcon(button, 'x-circle', true);
+  annotationPopover.innerHTML = button.getAttribute('data-annotation-content');
+
+  annotationPopover.classList.remove('is-above');
+  annotationPopover.style.visibility = 'hidden';
+  annotationPopover.classList.add('is-visible');
+
+  requestAnimationFrame(function() {
+    positionPopover(button);
+  });
+}
+
+function positionPopover(button) {
+  var rect = button.getBoundingClientRect();
+  var scrollX = window.scrollX;
+  var scrollY = window.scrollY;
+  var popoverRect = annotationPopover.getBoundingClientRect();
+  var gap = 6;
+  var padding = 12;
+  var viewportWidth = window.innerWidth;
+  var viewportHeight = window.innerHeight;
+
+  var left = rect.left + scrollX + (rect.width / 2) - (popoverRect.width / 2);
+  var spaceBelow = viewportHeight - rect.bottom;
+  var spaceAbove = rect.top;
+  var openAbove = spaceBelow < popoverRect.height + gap + padding && spaceAbove > spaceBelow;
+
+  var top;
+  if (openAbove) {
+    top = rect.top + scrollY - popoverRect.height - gap;
+    annotationPopover.classList.add('is-above');
+  } else {
+    top = rect.bottom + scrollY + gap;
+    annotationPopover.classList.remove('is-above');
+  }
+
+  if (left < padding) {
+    left = padding;
+  } else if (left + popoverRect.width > viewportWidth - padding) {
+    left = viewportWidth - popoverRect.width - padding;
+  }
+
+  var arrowLeft = rect.left + scrollX + (rect.width / 2) - left;
+  annotationPopover.style.setProperty('--arrow-left', Math.max(12, Math.min(arrowLeft, popoverRect.width - 12)) + 'px');
+  annotationPopover.style.left = left + 'px';
+  annotationPopover.style.top = top + 'px';
+  annotationPopover.style.visibility = 'visible';
+}
+
+function hideAnnotationPopover() {
+  if (!annotationPopover) return;
+  if (activeAnnotationButton) {
+    setAnnotationIcon(activeAnnotationButton, 'plus-circle', true);
+    activeAnnotationButton.classList.remove('is-active');
+  }
+  annotationPopover.classList.remove('is-visible');
+  activeAnnotationButton = null;
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', function() { initCodeAnnotations(); });
+} else {
+  initCodeAnnotations();
+}
+
+window.docyard = window.docyard || {};
+window.docyard.initCodeAnnotations = initCodeAnnotations;

data/lib/docyard/templates/assets/js/hot-reload.js

@@ -59,6 +59,7 @@
     if (docyard.initAbbreviations) docyard.initAbbreviations(container);
     if (docyard.initLightbox) docyard.initLightbox(container);
     if (docyard.initTooltips) docyard.initTooltips(container);
+    if (docyard.initCodeAnnotations) docyard.initCodeAnnotations(container);
   }
 
   function reloadContent() {