docyard 0.3.0 → 0.5.0

data/lib/docyard/rack_application.rb

@@ -3,6 +3,7 @@
 require "json"
 require "rack"
 require_relative "sidebar_builder"
+require_relative "prev_next_builder"
 require_relative "constants"
 
 module Docyard
@@ -12,7 +13,7 @@ module Docyard
       @file_watcher = file_watcher
       @config = config
       @router = Router.new(docs_path: docs_path)
-      @renderer = Renderer.new
+      @renderer = Renderer.new(base_url: config&.build&.base_url || "/")
       @asset_handler = AssetHandler.new
     end
 
@@ -46,9 +47,12 @@ module Docyard
     end
 
     def render_documentation_page(file_path, current_path)
+      sidebar_builder = build_sidebar_instance(current_path)
+
       html = renderer.render_file(
         file_path,
-        sidebar_html: build_sidebar(current_path),
+        sidebar_html: sidebar_builder.to_html,
+        prev_next_html: build_prev_next(sidebar_builder, current_path, file_path),
         branding: branding_options
       )
 
@@ -60,14 +64,32 @@ module Docyard
       [Constants::STATUS_NOT_FOUND, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
     end
 
-    def build_sidebar(current_path)
+    def build_sidebar_instance(current_path)
       SidebarBuilder.new(
         docs_path: docs_path,
         current_path: current_path,
         config: config
+      )
+    end
+
+    def build_prev_next(sidebar_builder, current_path, file_path)
+      markdown_content = File.read(file_path)
+      markdown = Markdown.new(markdown_content)
+
+      PrevNextBuilder.new(
+        sidebar_tree: sidebar_builder.tree,
+        current_path: current_path,
+        frontmatter: markdown.frontmatter,
+        config: navigation_config
       ).to_html
     end
 
+    def navigation_config
+      return {} unless config
+
+      config.navigation&.footer || {}
+    end
+
     def branding_options
       return default_branding unless config
 

data/lib/docyard/renderer.rb

@@ -9,30 +9,40 @@ module Docyard
     ERRORS_PATH = File.join(__dir__, "templates", "errors")
     PARTIALS_PATH = File.join(__dir__, "templates", "partials")
 
-    attr_reader :layout_path
+    attr_reader :layout_path, :base_url
 
-    def initialize(layout: "default")
+    def initialize(layout: "default", base_url: "/")
       @layout_path = File.join(LAYOUTS_PATH, "#{layout}.html.erb")
+      @base_url = normalize_base_url(base_url)
     end
 
-    def render_file(file_path, sidebar_html: "", branding: {})
+    def render_file(file_path, sidebar_html: "", prev_next_html: "", branding: {})
       markdown_content = File.read(file_path)
       markdown = Markdown.new(markdown_content)
 
       html_content = strip_md_from_links(markdown.html)
+      toc = markdown.toc
 
       render(
         content: html_content,
         page_title: markdown.title || Constants::DEFAULT_SITE_TITLE,
-        sidebar_html: sidebar_html,
+        navigation: {
+          sidebar_html: sidebar_html,
+          prev_next_html: prev_next_html,
+          toc: toc
+        },
         branding: branding
       )
     end
 
-    def render(content:, page_title: Constants::DEFAULT_SITE_TITLE, sidebar_html: "", branding: {})
+    def render(content:, page_title: Constants::DEFAULT_SITE_TITLE, navigation: {}, branding: {})
       template = File.read(layout_path)
 
-      assign_content_variables(content, page_title, sidebar_html)
+      sidebar_html = navigation[:sidebar_html] || ""
+      prev_next_html = navigation[:prev_next_html] || ""
+      toc = navigation[:toc] || []
+
+      assign_content_variables(content, page_title, sidebar_html, prev_next_html, toc)
       assign_branding_variables(branding)
 
       ERB.new(template).result(binding)
@@ -66,15 +76,30 @@ module Docyard
     def asset_path(path)
       return path if path.nil? || path.start_with?("http://", "https://")
 
-      "/#{path}"
+      "#{base_url}#{path}"
+    end
+
+    def link_path(path)
+      return path if path.nil? || path.start_with?("http://", "https://")
+
+      "#{base_url.chomp('/')}#{path}"
     end
 
     private
 
-    def assign_content_variables(content, page_title, sidebar_html)
+    def normalize_base_url(url)
+      return "/" if url.nil? || url.empty?
+
+      url = "/#{url}" unless url.start_with?("/")
+      url.end_with?("/") ? url : "#{url}/"
+    end
+
+    def assign_content_variables(content, page_title, sidebar_html, prev_next_html, toc)
       @content = content
       @page_title = page_title
       @sidebar_html = sidebar_html
+      @prev_next_html = prev_next_html
+      @toc = toc
     end
 
     def assign_branding_variables(branding)

data/lib/docyard/sidebar/config_parser.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "item"
+require_relative "title_extractor"
+
+module Docyard
+  module Sidebar
+    class ConfigParser
+      attr_reader :config_items, :docs_path, :current_path, :title_extractor
+
+      def initialize(config_items, docs_path:, current_path: "/", title_extractor: TitleExtractor.new)
+        @config_items = config_items || []
+        @docs_path = docs_path
+        @current_path = Utils::PathResolver.normalize(current_path)
+        @title_extractor = title_extractor
+      end
+
+      def parse
+        parse_items(config_items)
+      end
+
+      private
+
+      def parse_items(items, base_path = "")
+        items.map do |item_config|
+          parse_item(item_config, base_path)
+        end.compact
+      end
+
+      def parse_item(item_config, base_path)
+        case item_config
+        when String
+          resolve_file_item(item_config, base_path)
+        when Hash
+          parse_hash_item(item_config, base_path)
+        end
+      end
+
+      def parse_hash_item(item_config, base_path)
+        return parse_link_item(item_config) if link_item?(item_config)
+        return parse_nested_item(item_config, base_path) if nested_item?(item_config)
+        return resolve_file_item(item_config.keys.first, base_path, {}) if nil_value_item?(item_config)
+
+        slug = item_config.keys.first
+        options = item_config.values.first || {}
+        resolve_file_item(slug, base_path, options)
+      end
+
+      def link_item?(config)
+        config.key?("link") || config.key?(:link)
+      end
+
+      def nested_item?(config)
+        config.size == 1 && config.values.first.is_a?(Hash)
+      end
+
+      def nil_value_item?(config)
+        config.size == 1 && config.values.first.nil?
+      end
+
+      def parse_link_item(config)
+        link = config["link"] || config[:link]
+        text = config["text"] || config[:text]
+        icon = config["icon"] || config[:icon]
+        target = config["target"] || config[:target] || "_blank"
+
+        Item.new(
+          text: text,
+          link: link,
+          path: link,
+          icon: icon,
+          target: target,
+          type: :external
+        )
+      end
+
+      def parse_nested_item(item_config, base_path)
+        slug = item_config.keys.first.to_s
+        options = item_config.values.first || {}
+        nested_items = extract_nested_items(options)
+
+        dir_path = File.join(docs_path, base_path, slug)
+
+        if File.directory?(dir_path)
+          build_directory_item(slug, options, nested_items, base_path)
+        elsif nested_items.any?
+          build_file_with_children_item(slug, options, nested_items, base_path)
+        else
+          resolve_file_item(slug, base_path, options)
+        end
+      end
+
+      def extract_nested_items(options)
+        options["items"] || options[:items] || []
+      end
+
+      def extract_common_options(options)
+        {
+          text: options["text"] || options[:text],
+          icon: options["icon"] || options[:icon],
+          collapsed: options["collapsed"] || options[:collapsed] || false
+        }
+      end
+
+      def build_directory_item(slug, options, nested_items, base_path)
+        common_opts = extract_common_options(options)
+        new_base_path = File.join(base_path, slug)
+        parsed_items = parse_items(nested_items, new_base_path)
+
+        Item.new(
+          slug: slug,
+          text: common_opts[:text] || Utils::TextFormatter.titleize(slug),
+          icon: common_opts[:icon],
+          collapsed: common_opts[:collapsed],
+          items: parsed_items,
+          type: :directory
+        )
+      end
+
+      def build_file_with_children_item(slug, options, nested_items, base_path)
+        common_opts = extract_common_options(options)
+        file_path = File.join(docs_path, base_path, "#{slug}.md")
+        url_path = Utils::PathResolver.to_url(File.join(base_path, slug))
+        resolved_text = common_opts[:text] || extract_file_title(file_path, slug)
+
+        Item.new(
+          slug: slug,
+          text: resolved_text,
+          path: url_path,
+          icon: common_opts[:icon],
+          collapsed: common_opts[:collapsed],
+          items: parse_items(nested_items, base_path),
+          active: current_path == url_path,
+          type: :file
+        )
+      end
+
+      def extract_file_title(file_path, slug)
+        File.exist?(file_path) ? title_extractor.extract(file_path) : Utils::TextFormatter.titleize(slug)
+      end
+
+      def resolve_file_item(slug, base_path, options = {})
+        slug_str = slug.to_s
+        options ||= {}
+
+        file_path = File.join(docs_path, base_path, "#{slug_str}.md")
+        url_path = Utils::PathResolver.to_url(File.join(base_path, slug_str))
+
+        frontmatter = extract_frontmatter_metadata(file_path)
+        text = resolve_item_text(slug_str, file_path, options, frontmatter[:text])
+        icon = resolve_item_icon(options, frontmatter[:icon])
+        final_path = options["link"] || options[:link] || url_path
+
+        Item.new(
+          slug: slug_str, text: text, path: final_path, icon: icon,
+          active: current_path == final_path, type: :file
+        )
+      end
+
+      def extract_frontmatter_metadata(file_path)
+        return { text: nil, icon: nil } unless File.exist?(file_path)
+
+        markdown = Markdown.new(File.read(file_path))
+        {
+          text: markdown.sidebar_text || markdown.title,
+          icon: markdown.sidebar_icon
+        }
+      end
+
+      def resolve_item_text(slug, file_path, options, frontmatter_text)
+        text = options["text"] || options[:text] || frontmatter_text
+        text || extract_file_title(file_path, slug)
+      end
+
+      def resolve_item_icon(options, frontmatter_icon)
+        options["icon"] || options[:icon] || frontmatter_icon
+      end
+    end
+  end
+end

data/lib/docyard/sidebar/item.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class Item
+      attr_reader :slug, :text, :icon, :link, :target, :collapsed, :items, :path, :active, :type
+
+      def initialize(**options)
+        @slug = options[:slug]
+        @text = options[:text]
+        @icon = options[:icon]
+        @link = options[:link]
+        @target = options[:target] || "_self"
+        @collapsed = options[:collapsed] || false
+        @items = options[:items] || []
+        @path = options[:path] || options[:link]
+        @active = options[:active] || false
+        @type = options[:type] || :file
+      end
+
+      def external?
+        return false if path.nil?
+
+        path.start_with?("http://", "https://")
+      end
+
+      def children?
+        items.any?
+      end
+
+      def title
+        text
+      end
+
+      def children
+        items
+      end
+
+      def collapsible?
+        children?
+      end
+
+      def to_h
+        {
+          title: title,
+          path: path,
+          icon: icon,
+          active: active,
+          type: type,
+          collapsed: collapsed,
+          collapsible: collapsible?,
+          target: target,
+          children: children.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/docyard/sidebar/renderer.rb

@@ -7,10 +7,11 @@ module Docyard
     class Renderer
       PARTIALS_PATH = File.join(__dir__, "../templates/partials")
 
-      attr_reader :site_title
+      attr_reader :site_title, :base_url
 
-      def initialize(site_title: "Documentation")
+      def initialize(site_title: "Documentation", base_url: "/")
         @site_title = site_title
+        @base_url = normalize_base_url(base_url)
       end
 
       def render(tree)
@@ -34,8 +35,21 @@ module Docyard
         ERB.new(template).result(erb_binding)
       end
 
-      def icon(name)
-        render_partial(:icons, icon_name: name)
+      def icon(name, weight = "regular")
+        Icons.render(name.to_s.tr("_", "-"), weight) || ""
+      end
+
+      def link_path(path)
+        return path if path.nil? || path.start_with?("http://", "https://")
+
+        "#{base_url.chomp('/')}#{path}"
+      end
+
+      def normalize_base_url(url)
+        return "/" if url.nil? || url.empty?
+
+        url = "/#{url}" unless url.start_with?("/")
+        url.end_with?("/") ? url : "#{url}/"
       end
 
       def render_tree_with_sections(items)
@@ -98,12 +112,25 @@ module Docyard
       end
 
       def render_leaf_item(item)
-        render_partial(:nav_leaf, path: item[:path], title: item[:title], active: item[:active])
+        render_partial(
+          :nav_leaf,
+          path: item[:path],
+          title: item[:title],
+          active: item[:active],
+          icon: item[:icon],
+          target: item[:target]
+        )
       end
 
       def render_group_item(item)
         children_html = render_tree(item[:children])
-        render_partial(:nav_group, title: item[:title], children_html: children_html)
+        render_partial(
+          :nav_group,
+          title: item[:title],
+          children_html: children_html,
+          icon: item[:icon],
+          collapsed: item[:collapsed]
+        )
       end
     end
   end

data/lib/docyard/sidebar_builder.rb

@@ -4,6 +4,7 @@ require_relative "sidebar/file_system_scanner"
 require_relative "sidebar/title_extractor"
 require_relative "sidebar/tree_builder"
 require_relative "sidebar/renderer"
+require_relative "sidebar/config_parser"
 
 module Docyard
   class SidebarBuilder
@@ -26,10 +27,44 @@ module Docyard
     private
 
     def build_tree
+      if config_sidebar_items?
+        build_tree_from_config
+      else
+        build_tree_from_filesystem
+      end
+    end
+
+    def build_tree_from_config
+      config_parser.parse.map(&:to_h)
+    end
+
+    def build_tree_from_filesystem
       file_items = scanner.scan
       tree_builder.build(file_items)
     end
 
+    def config_sidebar_items?
+      config_sidebar_items&.any?
+    end
+
+    def config_sidebar_items
+      return [] unless config
+
+      if config.is_a?(Hash)
+        config.dig("sidebar", "items") || config.dig(:sidebar, :items) || []
+      else
+        config.sidebar&.items || []
+      end
+    end
+
+    def config_parser
+      @config_parser ||= Sidebar::ConfigParser.new(
+        config_sidebar_items,
+        docs_path: docs_path,
+        current_path: current_path
+      )
+    end
+
     def scanner
       @scanner ||= Sidebar::FileSystemScanner.new(docs_path)
     end
@@ -43,10 +78,19 @@ module Docyard
 
     def renderer
       @renderer ||= Sidebar::Renderer.new(
-        site_title: extract_site_title
+        site_title: extract_site_title,
+        base_url: extract_base_url
       )
     end
 
+    def extract_base_url
+      if config.is_a?(Hash)
+        config.dig(:build, :base_url) || "/"
+      else
+        config&.build&.base_url || "/"
+      end
+    end
+
     def extract_site_title
       if config.is_a?(Hash)
         config[:site_title] || "Documentation"

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

@@ -6,7 +6,7 @@
   margin: var(--space-6) 0;
   border: 1px solid;
   border-radius: var(--radius-lg);
-  transition: all var(--transition-base);
+  transition: border-color var(--transition-base), background-color var(--transition-base);
 }
 
 .docyard-callout__icon {

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

@@ -47,7 +47,7 @@
   background-color: var(--color-bg);
   color: var(--color-text-secondary);
   cursor: pointer;
-  transition: all var(--transition-base);
+  transition: background-color var(--transition-base), border-color var(--transition-base), color var(--transition-base), opacity var(--transition-base), visibility var(--transition-base);
   opacity: 0;
   visibility: hidden;
 }
@@ -78,7 +78,7 @@
 .docyard-code-block__copy svg {
   width: 16px;
   height: 16px;
-  transition: all 0.2s ease;
+  transition: transform 0.2s ease, opacity 0.2s ease;
 }
 
 /* Success state */

data/lib/docyard/templates/assets/css/components/heading-anchor.css

@@ -0,0 +1,77 @@
+.content h2[id],
+.content h3[id],
+.content h4[id],
+.content h5[id],
+.content h6[id] {
+  position: relative;
+  scroll-margin-top: 100px;
+}
+
+/* Tablet: Account for both primary + secondary header */
+@media (max-width: 1280px) and (min-width: 1025px) {
+  .content h2[id],
+  .content h3[id],
+  .content h4[id],
+  .content h5[id],
+  .content h6[id] {
+    scroll-margin-top: calc(var(--header-height) + 3rem + var(--space-4));
+  }
+}
+
+.heading-anchor {
+  float: left;
+  margin-left: -0.75em;
+  padding-right: 0.25em;
+  font-weight: var(--font-weight-normal);
+  color: var(--color-primary);
+  text-decoration: none !important;
+  opacity: 0;
+  transition: opacity var(--transition-fast);
+  cursor: pointer;
+  user-select: none;
+}
+
+.heading-anchor:hover,
+.heading-anchor:focus {
+  opacity: 1;
+  text-decoration: none !important;
+}
+
+.heading-anchor:active,
+.heading-anchor:visited {
+  text-decoration: none !important;
+}
+
+.heading-anchor:focus {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+
+.content h2[id]:hover .heading-anchor,
+.content h3[id]:hover .heading-anchor,
+.content h4[id]:hover .heading-anchor,
+.content h5[id]:hover .heading-anchor,
+.content h6[id]:hover .heading-anchor {
+  opacity: 1;
+}
+
+@media (max-width: 1024px) {
+  .heading-anchor {
+    position: static;
+    margin-left: var(--space-2);
+    float: none;
+    opacity: 0.6;
+  }
+
+  .heading-anchor:hover,
+  .heading-anchor:focus {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .heading-anchor {
+    transition: none;
+  }
+}