docyard 0.4.0 → 0.6.0

data/lib/docyard/components/tabs_range_finder.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Components
+    module TabsRangeFinder
+      module_function
+
+      def find_ranges(html)
+        ranges = []
+        start_pattern = '<div class="docyard-tabs"'
+
+        pos = 0
+        while (start_pos = html.index(start_pattern, pos))
+          end_pos = find_matching_close_div(html, start_pos)
+          ranges << (start_pos...end_pos) if end_pos
+          pos = end_pos || (start_pos + 1)
+        end
+        ranges
+      end
+
+      def find_matching_close_div(html, start_pos)
+        depth = 0
+        pos = start_pos
+
+        while pos < html.length
+          if html[pos, 4] == "<div"
+            depth += 1
+            pos += 4
+          elsif html[pos, 6] == "</div>"
+            depth -= 1
+            return pos + 6 if depth.zero?
+
+            pos += 6
+          else
+            pos += 1
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/docyard/config/validator.rb

@@ -12,6 +12,7 @@ module Docyard
         validate_site_section
         validate_branding_section
         validate_build_section
+        validate_markdown_section
 
         raise ConfigError, format_errors if @errors.any?
       end
@@ -48,6 +49,13 @@ module Docyard
         validate_boolean(build["clean"], "build.clean")
       end
 
+      def validate_markdown_section
+        markdown = @config["markdown"]
+        return unless markdown
+
+        validate_boolean(markdown["lineNumbers"], "markdown.lineNumbers") if markdown.key?("lineNumbers")
+      end
+
       def validate_string(value, field_name)
         return if value.nil?
         return if value.is_a?(String)

data/lib/docyard/config.rb

@@ -27,6 +27,16 @@ module Docyard
       },
       "sidebar" => {
         "items" => []
+      },
+      "navigation" => {
+        "footer" => {
+          "enabled" => true,
+          "prev_text" => "Previous",
+          "next_text" => "Next"
+        }
+      },
+      "markdown" => {
+        "lineNumbers" => false
       }
     }.freeze
 
@@ -63,6 +73,14 @@ module Docyard
       @sidebar ||= ConfigSection.new(data["sidebar"])
     end
 
+    def navigation
+      @navigation ||= ConfigSection.new(data["navigation"])
+    end
+
+    def markdown
+      @markdown ||= ConfigSection.new(data["markdown"])
+    end
+
     private
 
     def load_config_data

data/lib/docyard/icons/file_types.rb

@@ -8,7 +8,6 @@ module Docyard
     # License: CC BY-SA 4.0 (see LICENSE.vscode-icons)
     # Copyright (c) 2016 Roberto Huertas
     module FileTypes
-      # SVG content for each file type icon
       # rubocop:disable Layout/LineLength
       ICONS = {
         "css" => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" aria-labelledby="css-logo-title css-logo-description"><title>CSS Logo</title><g style="display:inline"><path fill="#639" d="M1.995 1.994h23.52a4.48 4.48 0 0 1 4.48 4.48v19.04a4.48 4.48 0 0 1-4.48 4.48H6.475a4.48 4.48 0 0 1-4.48-4.48Z"/><path fill="#fff" d="M9.079 24.87v-4.704c0-1.876 1.204-2.884 3.024-2.884 1.792-.028 2.912 1.148 2.856 3.136h-2.072c.056-.756-.28-1.316-.84-1.288-.7 0-.896.476-.896 1.372v4.088c0 .868.28 1.288.896 1.316.644 0 .896-.644.84-1.372h2.072c.112 2.044-1.176 3.248-2.996 3.22-1.764 0-2.884-.98-2.884-2.884zm6.636-.336h1.932c.028.896.308 1.456.924 1.456.616 0 .84-.364.84-1.204 0-.7-.308-1.092-1.064-1.456l-.728-.336c-1.288-.616-1.82-1.372-1.82-2.884 0-1.68 1.064-2.856 2.8-2.856 1.736 0 2.66 1.204 2.688 3.164h-1.876c0-.812-.168-1.372-.784-1.372-.56 0-.84.28-.84.98s.252.98.924 1.26l.672.308c1.428.672 2.044 1.54 2.044 3.164 0 1.932-1.092 2.996-2.884 2.996-1.792 0-2.8-1.232-2.828-3.22zm6.328 0h1.96c0 .896.308 1.456.896 1.456.588 0 .84-.364.84-1.204 0-.7-.28-1.092-1.064-1.456l-.728-.336c-1.288-.616-1.792-1.372-1.792-2.884 0-1.68 1.036-2.856 2.8-2.856 1.764 0 2.632 1.204 2.688 3.164h-1.876c-.028-.812-.196-1.372-.812-1.372-.56 0-.812.28-.812.98s.224.98.896 1.26l.7.308c1.4.672 2.016 1.54 2.016 3.164 0 1.932-1.092 2.996-2.884 2.996-1.792 0-2.8-1.232-2.828-3.22z"/></g></svg>',
@@ -35,7 +34,6 @@ module Docyard
       }.freeze
       # rubocop:enable Layout/LineLength
 
-      # Map of file extensions/aliases to icon names
       EXTENSIONS = {
         "css" => "css",
         "go" => "go",
@@ -62,10 +60,6 @@ module Docyard
         "postgresql" => "pgsql"
       }.freeze
 
-      # Get the SVG content for a file extension
-      #
-      # @param extension [String] The file extension (e.g., "js", "ts")
-      # @return [String, nil] The SVG content, or nil if not found
       def self.svg(extension)
         icon_name = EXTENSIONS[extension.to_s.downcase]
         return nil unless icon_name
@@ -73,17 +67,10 @@ module Docyard
         ICONS[icon_name]
       end
 
-      # Check if an icon exists for a file extension
-      #
-      # @param extension [String] The file extension to check
-      # @return [Boolean] true if icon exists
       def self.exists?(extension)
         EXTENSIONS.key?(extension.to_s.downcase)
       end
 
-      # Get all available file extensions
-      #
-      # @return [Array<String>] Array of supported extensions
       def self.available
         EXTENSIONS.keys.sort
       end

data/lib/docyard/icons/phosphor.rb

@@ -35,7 +35,8 @@ module Docyard
         "warning-octagon" => '<path d="M120,136V80a8,8,0,0,1,16,0v56a8,8,0,0,1-16,0ZM232,91.55v72.9a15.86,15.86,0,0,1-4.69,11.31l-51.55,51.55A15.86,15.86,0,0,1,164.45,232H91.55a15.86,15.86,0,0,1-11.31-4.69L28.69,175.76A15.86,15.86,0,0,1,24,164.45V91.55a15.86,15.86,0,0,1,4.69-11.31L80.24,28.69A15.86,15.86,0,0,1,91.55,24h72.9a15.86,15.86,0,0,1,11.31,4.69l51.55,51.55A15.86,15.86,0,0,1,232,91.55Zm-16,0L164.45,40H91.55L40,91.55v72.9L91.55,216h72.9L216,164.45ZM128,160a12,12,0,1,0,12,12A12,12,0,0,0,128,160Z"/>',
         "siren" => '<path d="M120,16V8a8,8,0,0,1,16,0v8a8,8,0,0,1-16,0Zm80,32a8,8,0,0,0,5.66-2.34l8-8a8,8,0,0,0-11.32-11.32l-8,8A8,8,0,0,0,200,48ZM50.34,45.66A8,8,0,0,0,61.66,34.34l-8-8A8,8,0,0,0,42.34,37.66Zm87,26.45a8,8,0,1,0-2.64,15.78C153.67,91.08,168,108.32,168,128a8,8,0,0,0,16,0C184,100.6,163.93,76.57,137.32,72.11ZM232,176v24a16,16,0,0,1-16,16H40a16,16,0,0,1-16-16V176a16,16,0,0,1,16-16V128a88,88,0,0,1,88.67-88c48.15.36,87.33,40.29,87.33,89v31A16,16,0,0,1,232,176ZM56,160H200V129c0-40-32.05-72.71-71.45-73H128a72,72,0,0,0-72,72Zm160,40V176H40v24H216Z"/>',
         "file" => '<path d="M213.66,82.34l-56-56A8,8,0,0,0,152,24H56A16,16,0,0,0,40,40V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V88A8,8,0,0,0,213.66,82.34ZM160,51.31,188.69,80H160ZM200,216H56V40h88V88a8,8,0,0,0,8,8h48V216Z"/>',
-        "terminal-window" => '<path d="M128,128a8,8,0,0,1-3,6.25l-40,32a8,8,0,1,1-10-12.5L107.19,128,75,102.25a8,8,0,1,1,10-12.5l40,32A8,8,0,0,1,128,128Zm48,24H136a8,8,0,0,0,0,16h40a8,8,0,0,0,0-16Zm56-96V200a16,16,0,0,1-16,16H40a16,16,0,0,1-16-16V56A16,16,0,0,1,40,40H216A16,16,0,0,1,232,56ZM216,200V56H40V200H216Z"/>'
+        "terminal-window" => '<path d="M128,128a8,8,0,0,1-3,6.25l-40,32a8,8,0,1,1-10-12.5L107.19,128,75,102.25a8,8,0,1,1,10-12.5l40,32A8,8,0,0,1,128,128Zm48,24H136a8,8,0,0,0,0,16h40a8,8,0,0,0,0-16Zm56-96V200a16,16,0,0,1-16,16H40a16,16,0,0,1-16-16V56A16,16,0,0,1,40,40H216A16,16,0,0,1,232,56ZM216,200V56H40V200H216Z"/>',
+        "list-dashes" => '<path d="M88,64a8,8,0,0,1,8-8H216a8,8,0,0,1,0,16H96A8,8,0,0,1,88,64Zm128,56H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Zm0,64H96a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16ZM56,56H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Zm0,64H40a8,8,0,0,0,0,16H56a8,8,0,0,0,0-16Z"/>'
       },
       "bold" => {
         "heart" => '<path d="M178,36c-20.09,0-37.92,7.93-50,21.56C115.92,43.93,98.09,36,78,36a66.08,66.08,0,0,0-66,66c0,72.34,105.81,130.14,110.31,132.57a12,12,0,0,0,11.38,0C138.19,232.14,244,174.34,244,102A66.08,66.08,0,0,0,178,36Zm-5.49,142.36A328.69,328.69,0,0,1,128,210.16a328.69,328.69,0,0,1-44.51-31.8C61.82,159.77,36,131.42,36,102A42,42,0,0,1,78,60c17.8,0,32.7,9.4,38.89,24.54a12,12,0,0,0,22.22,0C145.3,69.4,160.2,60,178,60a42,42,0,0,1,42,42C220,131.42,194.18,159.77,172.51,178.36Z"/>'

data/lib/docyard/markdown.rb

@@ -9,16 +9,24 @@ require_relative "components/callout_processor"
 require_relative "components/tabs_processor"
 require_relative "components/icon_processor"
 require_relative "components/code_block_processor"
+require_relative "components/code_snippet_import_preprocessor"
+require_relative "components/code_block_options_preprocessor"
+require_relative "components/code_block_diff_preprocessor"
+require_relative "components/code_block_focus_preprocessor"
 require_relative "components/table_wrapper_processor"
+require_relative "components/heading_anchor_processor"
+require_relative "components/table_of_contents_processor"
 
 module Docyard
   class Markdown
     FRONTMATTER_REGEX = /\A---\s*\n(.*?\n)---\s*\n/m
 
-    attr_reader :raw
+    attr_reader :raw, :config
 
-    def initialize(raw)
+    def initialize(raw, config: nil)
       @raw = raw.freeze
+      @config = config
+      @context = {}
     end
 
     def frontmatter
@@ -53,6 +61,10 @@ module Docyard
       frontmatter.dig("sidebar", "collapsed")
     end
 
+    def toc
+      @context[:toc] || []
+    end
+
     private
 
     def parse_frontmatter
@@ -69,7 +81,9 @@ module Docyard
     end
 
     def render_html
-      preprocessed_content = Components::Registry.run_preprocessors(content)
+      @context[:config] = config&.data
+
+      preprocessed_content = Components::Registry.run_preprocessors(content, @context)
 
       raw_html = Kramdown::Document.new(
         preprocessed_content,
@@ -79,7 +93,7 @@ module Docyard
         parse_block_html: true
       ).to_html
 
-      Components::Registry.run_postprocessors(raw_html)
+      Components::Registry.run_postprocessors(raw_html, @context)
     end
   end
 end

data/lib/docyard/prev_next_builder.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative "renderer"
+require_relative "utils/path_resolver"
+
+module Docyard
+  class PrevNextBuilder
+    attr_reader :sidebar_tree, :current_path, :frontmatter, :config
+
+    def initialize(sidebar_tree:, current_path:, frontmatter: {}, config: {})
+      @sidebar_tree = sidebar_tree
+      @current_path = Utils::PathResolver.normalize(current_path)
+      @frontmatter = frontmatter
+      @config = config
+    end
+
+    def prev_next_links
+      return nil unless enabled?
+
+      {
+        prev: build_prev_link,
+        next: build_next_link
+      }
+    end
+
+    def to_html
+      links = prev_next_links
+      return "" if links.nil? || (links[:prev].nil? && links[:next].nil?)
+
+      Renderer.new.render_partial(
+        "_prev_next", {
+          prev: links[:prev],
+          next: links[:next],
+          prev_text: config_prev_text,
+          next_text: config_next_text
+        }
+      )
+    end
+
+    private
+
+    def enabled?
+      return false if config_disabled?
+      return false if frontmatter_disabled?
+
+      true
+    end
+
+    def config_disabled?
+      return false if config.nil? || config.empty?
+
+      config == false || config["enabled"] == false || config[:enabled] == false
+    end
+
+    def frontmatter_disabled?
+      frontmatter["prev"] == false && frontmatter["next"] == false
+    end
+
+    def build_prev_link
+      return nil if frontmatter["prev"] == false
+
+      return build_frontmatter_link(frontmatter["prev"]) if frontmatter["prev"]
+
+      auto_prev_link
+    end
+
+    def build_next_link
+      return nil if frontmatter["next"] == false
+
+      return build_frontmatter_link(frontmatter["next"]) if frontmatter["next"]
+
+      auto_next_link
+    end
+
+    def build_frontmatter_link(value)
+      case value
+      when String
+        find_link_by_text(value)
+      when Hash
+        {
+          title: value["text"] || value[:text],
+          path: value["link"] || value[:link]
+        }
+      end
+    end
+
+    def find_link_by_text(text)
+      flat_links.find { |link| link[:title].downcase == text.downcase }
+    end
+
+    def auto_prev_link
+      index = current_page_index
+      return nil unless index&.positive?
+
+      flat_links[index - 1]
+    end
+
+    def auto_next_link
+      index = current_page_index
+      return nil unless index && index < flat_links.length - 1
+
+      flat_links[index + 1]
+    end
+
+    def current_page_index
+      @current_page_index ||= flat_links.find_index do |link|
+        normalized_path(link[:path]) == normalized_path(current_path)
+      end
+    end
+
+    def flat_links
+      @flat_links ||= begin
+        links = []
+        flatten_tree(sidebar_tree, links)
+        links.uniq { |link| normalized_path(link[:path]) }
+      end
+    end
+
+    def flatten_tree(items, links)
+      items.each do |item|
+        links << build_link(item) if valid_navigation_item?(item)
+        flatten_tree(item[:children], links) if item[:children]&.any?
+      end
+    end
+
+    def valid_navigation_item?(item)
+      item[:type] == :file && item[:path] && !external_link?(item[:path])
+    end
+
+    def build_link(item)
+      {
+        title: item[:footer_text] || item[:title],
+        path: item[:path]
+      }
+    end
+
+    def external_link?(path)
+      path.start_with?("http://", "https://")
+    end
+
+    def normalized_path(path)
+      return "" if path.nil?
+
+      path.gsub(/[?#].*$/, "")
+    end
+
+    def config_prev_text
+      return "Previous" if config.nil? || config.empty?
+
+      config["prev_text"] || config[:prev_text] || "Previous"
+    end
+
+    def config_next_text
+      return "Next" if config.nil? || config.empty?
+
+      config["next_text"] || config[:next_text] || "Next"
+    end
+  end
+end

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(base_url: config&.build&.base_url || "/")
+      @renderer = Renderer.new(base_url: config&.build&.base_url || "/", config: config)
       @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,31 +9,41 @@ module Docyard
     ERRORS_PATH = File.join(__dir__, "templates", "errors")
     PARTIALS_PATH = File.join(__dir__, "templates", "partials")
 
-    attr_reader :layout_path, :base_url
+    attr_reader :layout_path, :base_url, :config
 
-    def initialize(layout: "default", base_url: "/")
+    def initialize(layout: "default", base_url: "/", config: nil)
       @layout_path = File.join(LAYOUTS_PATH, "#{layout}.html.erb")
       @base_url = normalize_base_url(base_url)
+      @config = config
     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)
+      markdown = Markdown.new(markdown_content, config: config)
 
       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)
@@ -85,10 +95,12 @@ module Docyard
       url.end_with?("/") ? url : "#{url}/"
     end
 
-    def assign_content_variables(content, page_title, sidebar_html)
+    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/templates/assets/css/code.css

@@ -42,12 +42,16 @@
   margin: 0;
 }
 
-.highlight,
-.highlight .w {
+.highlight {
   color: #24292f;
   background-color: #f6f8fa;
 }
 
+.highlight .w {
+  color: #24292f;
+  background-color: transparent;
+}
+
 /* Keywords */
 .highlight .k,
 .highlight .kd,
@@ -214,12 +218,16 @@
 }
 
 /* Dark Mode Syntax Highlighting - GitHub Dark */
-.dark .highlight,
-.dark .highlight .w {
+.dark .highlight {
   color: #e6edf3;
   background-color: #161b22;
 }
 
+.dark .highlight .w {
+  color: #e6edf3;
+  background-color: transparent;
+}
+
 /* Keywords */
 .dark .highlight .k,
 .dark .highlight .kd,