docyard 0.9.0 → 1.0.1

data/lib/docyard/navigation/sidebar_builder.rb

@@ -1,27 +1,27 @@
 # frozen_string_literal: true
 
-require_relative "sidebar/file_system_scanner"
-require_relative "sidebar/title_extractor"
-require_relative "sidebar/tree_builder"
+require_relative "sidebar/cache"
+require_relative "sidebar/config_builder"
+require_relative "sidebar/auto_builder"
+require_relative "sidebar/distributed_builder"
 require_relative "sidebar/renderer"
-require_relative "sidebar/config_parser"
-require_relative "sidebar/local_config_loader"
-require_relative "sidebar/path_prefixer"
 require_relative "sidebar/tree_filter"
+require_relative "sidebar/local_config_loader"
 
 module Docyard
   class SidebarBuilder
-    attr_reader :docs_path, :current_path, :config, :header_ctas
+    attr_reader :docs_path, :current_path, :config, :header_ctas, :sidebar_cache
 
-    def initialize(docs_path:, current_path: "/", config: nil, header_ctas: [])
+    def initialize(docs_path:, current_path: "/", config: nil, header_ctas: [], sidebar_cache: nil)
       @docs_path = docs_path
       @current_path = current_path
       @config = config
       @header_ctas = header_ctas
+      @sidebar_cache = sidebar_cache
     end
 
     def tree
-      @tree ||= build_scoped_tree
+      @tree ||= build_tree
     end
 
     def to_html
@@ -30,101 +30,63 @@ module Docyard
 
     private
 
-    def build_scoped_tree
-      active_tab = find_active_tab
-      return build_tree_for_path(docs_path) unless active_tab
-
-      build_tree_for_tab(active_tab)
-    end
-
-    def build_tree_for_tab(tab)
-      tab_path = tab["href"]&.chomp("/")
-      return build_tree_for_path(docs_path) if empty_tab_path?(tab_path)
+    def build_tree
+      return build_from_cache if sidebar_cache&.valid?
 
-      scoped_docs_path = resolve_scoped_path(tab_path)
-      build_scoped_or_filtered_tree(scoped_docs_path, tab_path)
+      build_without_cache
     end
 
-    def empty_tab_path?(tab_path)
-      tab_path.nil? || tab_path.empty? || tab_path == "/"
+    def build_from_cache
+      base_tree = sidebar_cache.get(current_path: current_path)
+      apply_tab_scoping(base_tree)
     end
 
-    def resolve_scoped_path(tab_path)
-      tab_folder = tab_path.sub(%r{^/}, "")
-      File.join(docs_path, tab_folder)
+    def build_without_cache
+      base_tree = build_tree_for_mode
+      apply_tab_scoping(base_tree)
     end
 
-    def build_scoped_or_filtered_tree(scoped_docs_path, tab_path)
-      if scoped_sidebar_available?(scoped_docs_path)
-        build_tree_for_path(scoped_docs_path, base_url_prefix: tab_path)
+    def build_tree_for_mode
+      case sidebar_mode
+      when "auto"
+        Sidebar::AutoBuilder.new(docs_path, current_path: current_path).build
+      when "distributed"
+        Sidebar::DistributedBuilder.new(docs_path, current_path: current_path).build
       else
-        Sidebar::TreeFilter.new(build_tree_for_path(docs_path), tab_path).filter
+        build_config_tree
       end
     end
 
-    def scoped_sidebar_available?(path)
-      File.directory?(path) && Sidebar::LocalConfigLoader.new(path).config_file_exists?
-    end
+    def build_config_tree
+      config_items = Sidebar::LocalConfigLoader.new(docs_path).load
+      return [] unless config_items
 
-    def build_tree_for_path(path, base_url_prefix: "")
-      config_items = Sidebar::LocalConfigLoader.new(path).load
-      tree = build_tree(config_items, path, base_url_prefix)
-      maybe_prepend_overview(tree, path, base_url_prefix)
+      Sidebar::ConfigBuilder.new(config_items, current_path: current_path).build
     end
 
-    def build_tree(config_items, path, base_url_prefix)
-      if config_items&.any?
-        build_tree_from_config(config_items, path, base_url_prefix)
-      else
-        build_tree_from_filesystem(path, base_url_prefix)
-      end
+    def sidebar_mode
+      config&.sidebar || "config"
     end
 
-    def maybe_prepend_overview(tree, path, base_url_prefix)
-      return tree if skip_overview?(tree, path, base_url_prefix)
+    def apply_tab_scoping(base_tree)
+      return base_tree if sidebar_mode == "auto"
+      return base_tree unless tabs_configured?
 
-      [build_overview_item(base_url_prefix)] + tree
-    end
-
-    def skip_overview?(tree, path, base_url_prefix)
-      base_url_prefix.empty? ||
-        tree.first&.dig(:section) ||
-        !File.file?(File.join(path, "index.md")) ||
-        tree.any? { |item| item[:path] == base_url_prefix }
-    end
-
-    def build_overview_item(base_url_prefix)
-      {
-        title: "Overview", path: base_url_prefix, icon: nil,
-        active: current_path == base_url_prefix, type: :file,
-        collapsed: false, collapsible: false, target: "_self",
-        has_index: false, section: false, children: []
-      }
-    end
-
-    def build_tree_from_config(items, path, base_url_prefix)
-      tree = Sidebar::ConfigParser.new(
-        items, docs_path: path, current_path: current_path_relative_to(base_url_prefix)
-      ).parse.map(&:to_h)
+      active_tab = find_active_tab
+      return base_tree unless active_tab
 
-      Sidebar::PathPrefixer.new(tree, base_url_prefix).prefix
+      filter_tree_for_tab(base_tree, active_tab)
     end
 
-    def build_tree_from_filesystem(path, base_url_prefix)
-      file_items = Sidebar::FileSystemScanner.new(path).scan
-      tree = Sidebar::TreeBuilder.new(
-        docs_path: path, current_path: current_path_relative_to(base_url_prefix)
-      ).build(file_items)
+    def filter_tree_for_tab(base_tree, tab)
+      tab_path = tab["href"]&.chomp("/")
+      return base_tree if empty_tab_path?(tab_path)
 
-      Sidebar::PathPrefixer.new(tree, base_url_prefix).prefix
+      Sidebar::TreeFilter.new(base_tree, tab_path).filter
     end
 
-    def current_path_relative_to(prefix)
-      return current_path if prefix.empty?
-      return current_path unless current_path.start_with?(prefix)
-
-      relative = current_path.sub(prefix, "")
-      relative.empty? ? "/" : relative
+    def empty_tab_path?(tab_path)
+      tab_path.nil? || tab_path.empty? || tab_path == "/"
     end
 
     def renderer

data/lib/docyard/rendering/branding_variables.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Docyard
+  module BrandingVariables
+    private
+
+    def assign_branding_variables(branding, current_path = "/")
+      assign_site_branding(branding)
+      assign_search_options(branding)
+      assign_credits_and_social(branding)
+      assign_tabs(branding, current_path)
+      assign_analytics(branding)
+    end
+
+    def assign_site_branding(branding)
+      @site_title = branding[:site_title] || Constants::DEFAULT_SITE_TITLE
+      @site_description = branding[:site_description] || ""
+      @logo = branding[:logo] || Constants::DEFAULT_LOGO_PATH
+      @logo_dark = branding[:logo_dark]
+      @favicon = branding[:favicon] || Constants::DEFAULT_FAVICON_PATH
+      @has_custom_logo = branding[:has_custom_logo] || false
+      @primary_color = branding[:primary_color]
+    end
+
+    def assign_search_options(branding)
+      @search_enabled = branding[:search_enabled].nil? || branding[:search_enabled]
+      @search_placeholder = branding[:search_placeholder] || "Search documentation..."
+    end
+
+    def assign_credits_and_social(branding)
+      @credits = branding[:credits] != false
+      @copyright = branding[:copyright]
+      @social = branding[:social] || []
+      @header_ctas = branding[:header_ctas] || []
+      @announcement = branding[:announcement]
+    end
+
+    def assign_analytics(branding)
+      @has_analytics = branding[:has_analytics] || false
+      @analytics_google = branding[:analytics_google]
+      @analytics_plausible = branding[:analytics_plausible]
+      @analytics_fathom = branding[:analytics_fathom]
+      @analytics_script = branding[:analytics_script]
+    end
+
+    def assign_tabs(branding, current_path)
+      tabs = branding[:tabs] || []
+      @tabs = tabs.map { |tab| tab.merge(active: tab_active?(tab[:href], current_path)) }
+      @has_tabs = branding[:has_tabs] || false
+      @current_path = current_path
+    end
+
+    def tab_active?(tab_href, current_path)
+      return false if tab_href.nil? || current_path.nil?
+      return false if tab_href.start_with?("http://", "https://")
+
+      normalized_tab = tab_href.chomp("/")
+      normalized_current = current_path.chomp("/")
+
+      return true if normalized_tab == normalized_current
+
+      current_path.start_with?("#{normalized_tab}/")
+    end
+  end
+end

data/lib/docyard/rendering/icon_helpers.rb

@@ -2,12 +2,25 @@
 
 module Docyard
   module IconHelpers
+    VALID_WEIGHTS = %w[regular bold fill light thin duotone].freeze
+
     def icon(name, weight = "regular")
-      Icons.render(name.to_s.tr("_", "-"), weight) || ""
+      name = name.to_s
+      return name if name.strip.start_with?("<svg")
+
+      name = name.tr("_", "-")
+      weight = weight.to_s
+      weight = "regular" unless VALID_WEIGHTS.include?(weight)
+      weight_class = weight == "regular" ? "ph" : "ph-#{weight}"
+      %(<i class="#{weight_class} ph-#{name}" aria-hidden="true"></i>)
     end
 
     def icon_file_extension(extension)
       Icons.render_file_extension(extension) || ""
     end
+
+    def icon_for_language(language)
+      Icons.render_for_language(language) || ""
+    end
   end
 end

data/lib/docyard/rendering/icons/devicons.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Icons
+    module Devicons
+      MAP = {
+        "bash" => "devicon-bash-plain", "bun" => "devicon-bun-plain colored",
+        "c" => "devicon-c-plain colored", "cargo" => "devicon-rust-original colored",
+        "clj" => "devicon-clojure-plain colored", "clojure" => "devicon-clojure-plain colored",
+        "coffee" => "devicon-coffeescript-original colored", "coffeescript" => "devicon-coffeescript-original colored",
+        "composer" => "devicon-composer-plain colored", "cpp" => "devicon-cplusplus-plain colored",
+        "cs" => "devicon-csharp-plain colored", "csharp" => "devicon-csharp-plain colored",
+        "css" => "devicon-css3-plain colored", "dart" => "devicon-dart-plain colored",
+        "docker" => "devicon-docker-plain colored", "dockerfile" => "devicon-docker-plain colored",
+        "elixir" => "devicon-elixir-plain colored", "elm" => "devicon-elm-plain colored",
+        "erb" => "devicon-ruby-plain colored", "erl" => "devicon-erlang-plain colored",
+        "erlang" => "devicon-erlang-plain colored", "ex" => "devicon-elixir-plain colored",
+        "gem" => "devicon-ruby-plain colored", "go" => "devicon-go-plain colored",
+        "golang" => "devicon-go-plain colored", "gql" => "devicon-graphql-plain colored",
+        "gradle" => "devicon-gradle-original colored", "graphql" => "devicon-graphql-plain colored",
+        "groovy" => "devicon-groovy-plain colored", "h" => "devicon-c-plain colored",
+        "haml" => "devicon-ruby-plain colored", "haskell" => "devicon-haskell-plain colored",
+        "homebrew" => "devicon-homebrew-plain colored", "hs" => "devicon-haskell-plain colored",
+        "htm" => "devicon-html5-plain colored", "html" => "devicon-html5-plain colored",
+        "html5" => "devicon-html5-plain colored", "java" => "devicon-java-plain colored",
+        "javascript" => "devicon-javascript-plain colored", "js" => "devicon-javascript-plain colored",
+        "json" => "devicon-json-plain colored", "jsx" => "devicon-react-original colored",
+        "kotlin" => "devicon-kotlin-plain colored", "kt" => "devicon-kotlin-plain colored",
+        "less" => "devicon-less-plain-wordmark colored", "lua" => "devicon-lua-plain colored",
+        "markdown" => "devicon-markdown-original", "maven" => "devicon-maven-plain colored",
+        "md" => "devicon-markdown-original", "mysql" => "devicon-mysql-plain colored",
+        "nginx" => "devicon-nginx-original colored", "nim" => "devicon-nim-plain colored",
+        "nix" => "devicon-nixos-plain colored", "npm" => "devicon-npm-original-wordmark colored",
+        "nuget" => "devicon-nuget-original colored", "objc" => "devicon-objectivec-plain colored",
+        "objectivec" => "devicon-objectivec-plain colored", "ocaml" => "devicon-ocaml-plain colored",
+        "pacman" => "devicon-archlinux-plain colored", "perl" => "devicon-perl-plain colored",
+        "pgsql" => "devicon-postgresql-plain colored", "php" => "devicon-php-plain colored",
+        "pip" => "devicon-python-plain colored", "pl" => "devicon-perl-plain colored",
+        "pnpm" => "devicon-pnpm-plain colored", "postgres" => "devicon-postgresql-plain colored",
+        "postgresql" => "devicon-postgresql-plain colored", "py" => "devicon-python-plain colored",
+        "python" => "devicon-python-plain colored", "r" => "devicon-r-plain colored",
+        "rb" => "devicon-ruby-plain colored", "rs" => "devicon-rust-original colored",
+        "ruby" => "devicon-ruby-plain colored", "rust" => "devicon-rust-original colored",
+        "sass" => "devicon-sass-original colored", "scala" => "devicon-scala-plain colored",
+        "scss" => "devicon-sass-original colored", "sql" => "devicon-azuresqldatabase-plain colored",
+        "svelte" => "devicon-svelte-plain colored", "swift" => "devicon-swift-plain colored",
+        "terraform" => "devicon-terraform-plain colored", "tf" => "devicon-terraform-plain colored",
+        "ts" => "devicon-typescript-plain colored", "tsx" => "devicon-react-original colored",
+        "typescript" => "devicon-typescript-plain colored", "vim" => "devicon-vim-plain colored",
+        "vue" => "devicon-vuejs-plain colored", "xml" => "devicon-xml-plain colored",
+        "yaml" => "devicon-yaml-plain colored", "yml" => "devicon-yaml-plain colored",
+        "yarn" => "devicon-yarn-plain colored", "zig" => "devicon-zig-plain colored"
+      }.freeze
+
+      HIGHLIGHT_ALIASES = {
+        "apt" => "bash", "bun" => "bash", "cargo" => "bash", "composer" => "bash",
+        "gem" => "bash", "gradle" => "bash", "homebrew" => "bash", "maven" => "bash",
+        "npm" => "bash", "nuget" => "bash", "pacman" => "bash", "pip" => "bash",
+        "pnpm" => "bash", "yarn" => "bash"
+      }.freeze
+    end
+  end
+end

data/lib/docyard/rendering/icons.rb

@@ -1,40 +1,39 @@
 # frozen_string_literal: true
 
-require_relative "icons/phosphor"
-require_relative "icons/file_types"
-require_relative "renderer"
+require_relative "icons/devicons"
 
 module Docyard
   module Icons
-    LIBRARIES = {
-      phosphor: PHOSPHOR
-    }.freeze
+    VALID_WEIGHTS = %w[regular bold fill light thin duotone].freeze
 
     def self.render(name, weight = "regular")
-      icon_data = LIBRARIES.dig(:phosphor, weight, name)
-      return nil unless icon_data
-
-      Renderer.new.render_partial(
-        "_icon", {
-          name: name,
-          icon_data: icon_data
-        }
-      )
+      name = name.to_s.tr("_", "-")
+      weight = weight.to_s
+      weight = "regular" unless VALID_WEIGHTS.include?(weight)
+      weight_class = weight == "regular" ? "ph" : "ph-#{weight}"
+      %(<i class="#{weight_class} ph-#{name}" aria-hidden="true"></i>)
+    end
+
+    def self.render_for_language(language)
+      devicon_class = Devicons::MAP[language.to_s.downcase]
+      return %(<i class="#{devicon_class}" aria-hidden="true"></i>) if devicon_class
+
+      ""
     end
 
     def self.render_file_extension(extension)
-      svg_content = FileTypes.svg(extension)
-
-      if svg_content
-        Renderer.new.render_partial(
-          "_icon_file_extension", {
-            extension: extension,
-            svg_content: svg_content
-          }
-        )
-      else
-        render("file")
-      end
+      devicon_class = Devicons::MAP[extension.to_s.downcase]
+      return %(<i class="#{devicon_class}" aria-hidden="true"></i>) if devicon_class
+
+      ""
+    end
+
+    def self.highlight_language(language)
+      Devicons::HIGHLIGHT_ALIASES[language.to_s.downcase] || language
+    end
+
+    def self.devicon?(language)
+      Devicons::MAP.key?(language.to_s.downcase)
     end
   end
 end

data/lib/docyard/rendering/markdown.rb

@@ -19,6 +19,8 @@ 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_extended_fence_preprocessor"
+require_relative "../components/processors/code_block_extended_fence_postprocessor"
 require_relative "../components/processors/table_wrapper_processor"
 require_relative "../components/processors/heading_anchor_processor"
 require_relative "../components/processors/custom_anchor_processor"
@@ -63,28 +65,8 @@ module Docyard
       frontmatter["description"]
     end
 
-    def sidebar_icon
-      frontmatter.dig("sidebar", "icon")
-    end
-
-    def sidebar_text
-      frontmatter.dig("sidebar", "text")
-    end
-
-    def sidebar_collapsed
-      frontmatter.dig("sidebar", "collapsed")
-    end
-
-    def sidebar_order
-      frontmatter.dig("sidebar", "order")
-    end
-
-    def sidebar_badge
-      frontmatter.dig("sidebar", "badge")
-    end
-
-    def sidebar_badge_type
-      frontmatter.dig("sidebar", "badge_type")
+    def og_image
+      frontmatter["og_image"]
     end
 
     def toc
@@ -109,7 +91,7 @@ module Docyard
     def render_html
       @context[:config] = config&.data
       @context[:current_file] = @file_path
-      @context[:docs_root] = "docs"
+      @context[:docs_root] = config&.source || "docs"
 
       preprocessed_content = Components::Registry.run_preprocessors(content, @context)
 

data/lib/docyard/rendering/og_helpers.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Docyard
+  module OgHelpers
+    def assign_og_variables(branding, page_description, page_og_image, current_path)
+      site_url = branding[:site_url]
+      @og_enabled = !site_url.nil? && !site_url.empty?
+      return unless @og_enabled
+
+      @og_url = build_canonical_url(site_url, current_path)
+      @og_description = page_description || @site_description
+      @og_image = build_og_image_url(site_url, page_og_image || branding[:og_image])
+      @og_twitter = branding[:twitter]
+    end
+
+    private
+
+    def build_canonical_url(site_url, current_path)
+      base = site_url.chomp("/")
+      path = current_path.start_with?("/") ? current_path : "/#{current_path}"
+      "#{base}#{path}"
+    end
+
+    def build_og_image_url(site_url, og_image)
+      return nil if og_image.nil?
+
+      if og_image.start_with?("http://", "https://")
+        og_image
+      else
+        base = site_url.chomp("/")
+        path = og_image.start_with?("/") ? og_image : "/#{og_image}"
+        "#{base}#{path}"
+      end
+    end
+  end
+end