docyard 0.9.0 → 1.0.0

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

data/lib/docyard/rendering/renderer.rb

@@ -1,53 +1,84 @@
 # frozen_string_literal: true
 
 require "erb"
-require_relative "../config/constants"
+require_relative "../constants"
+require_relative "../utils/git_info"
 require_relative "icon_helpers"
+require_relative "og_helpers"
+require_relative "branding_variables"
 
 module Docyard
   class Renderer
     include Utils::UrlHelpers
+    include Utils::HtmlHelpers
     include IconHelpers
+    include OgHelpers
+    include BrandingVariables
 
     LAYOUTS_PATH = File.join(__dir__, "../templates", "layouts")
     ERRORS_PATH = File.join(__dir__, "../templates", "errors")
     PARTIALS_PATH = File.join(__dir__, "../templates", "partials")
     DEFAULT_LAYOUT = "default"
 
-    attr_reader :base_url, :config
+    attr_reader :base_url, :config, :dev_mode, :sse_port
 
-    def initialize(base_url: "/", config: nil)
+    def initialize(base_url: "/", config: nil, dev_mode: false, sse_port: nil)
       @base_url = normalize_base_url(base_url)
       @config = config
+      @dev_mode = dev_mode
+      @sse_port = sse_port
     end
 
     def render_file(file_path, sidebar_html: "", prev_next_html: "", breadcrumbs: nil, branding: {},
                     template_options: {}, current_path: "/")
-      markdown = Markdown.new(File.read(file_path), config: config, file_path: file_path)
+      raw_content = File.read(file_path)
+      markdown = Markdown.new(raw_content, config: config, file_path: file_path)
 
       render(
         content: strip_md_from_links(markdown.html),
         page_title: markdown.title || Constants::DEFAULT_SITE_TITLE,
+        page_description: markdown.description,
+        page_og_image: markdown.og_image,
         navigation: build_navigation(sidebar_html, prev_next_html, markdown.toc, breadcrumbs),
         branding: branding,
         template_options: template_options,
-        current_path: current_path
+        current_path: current_path,
+        file_path: file_path,
+        raw_markdown: raw_content
       )
     end
 
+    def render_for_search(file_path)
+      markdown = Markdown.new(File.read(file_path), config: config, file_path: file_path)
+      title = markdown.title || Constants::DEFAULT_SITE_TITLE
+      content = strip_md_from_links(markdown.html)
+
+      <<~HTML
+        <!DOCTYPE html>
+        <html>
+        <head><title>#{escape_html(title)}</title></head>
+        <body><main data-pagefind-body>#{content}</main></body>
+        </html>
+      HTML
+    end
+
     def build_navigation(sidebar_html, prev_next_html, toc, breadcrumbs)
       { sidebar_html: sidebar_html, prev_next_html: prev_next_html, toc: toc, breadcrumbs: breadcrumbs }
     end
 
-    def render(content:, page_title: Constants::DEFAULT_SITE_TITLE, navigation: {}, branding: {},
-               template_options: {}, current_path: "/")
+    def render(content:, page_title: Constants::DEFAULT_SITE_TITLE, page_description: nil, page_og_image: nil,
+               navigation: {}, branding: {}, template_options: {}, current_path: "/", file_path: nil,
+               raw_markdown: nil)
       layout = template_options[:template] || DEFAULT_LAYOUT
       layout_path = File.join(LAYOUTS_PATH, "#{layout}.html.erb")
       template = File.read(layout_path)
 
-      assign_content_variables(content, page_title, navigation)
+      assign_content_variables(content, page_title, navigation, raw_markdown)
       assign_branding_variables(branding, current_path)
+      assign_og_variables(branding, page_description, page_og_image, current_path)
       assign_template_variables(template_options)
+      assign_git_info(branding, file_path)
+      assign_feedback_variables
 
       ERB.new(template).result(binding)
     end
@@ -58,7 +89,7 @@ module Docyard
 
     def render_server_error(error)
       @error_message = error.message
-      @backtrace = error.backtrace.join("\n")
+      @backtrace = error.backtrace&.join("\n") || "No backtrace available"
       render_error_template(500)
     end
 
@@ -68,15 +99,37 @@ module Docyard
       ERB.new(template).result(binding)
     end
 
+    VALID_IVAR_PATTERN = /\A[a-z_][a-z0-9_]*\z/i
+
     def render_partial(name, locals = {})
       partial_path = File.join(PARTIALS_PATH, "#{name}.html.erb")
       template = File.read(partial_path)
 
-      locals.each { |key, value| instance_variable_set("@#{key}", value) }
+      locals.each do |key, value|
+        validate_variable_name!(key)
+        instance_variable_set("@#{key}", value)
+      end
 
       ERB.new(template).result(binding)
     end
 
+    def render_custom_visual(file_path)
+      return "" if file_path.nil? || file_path.empty?
+
+      source_dir = config&.source || "docs"
+      full_path = File.join(source_dir, file_path)
+
+      return "" unless File.exist?(full_path)
+
+      File.read(full_path)
+    end
+
+    def validate_variable_name!(name)
+      return if name.to_s.match?(VALID_IVAR_PATTERN)
+
+      raise ArgumentError, "Invalid variable name: #{name}"
+    end
+
     def asset_path(path)
       return path if path.nil? || path.start_with?("http://", "https://")
 
@@ -85,61 +138,14 @@ module Docyard
 
     private
 
-    def assign_content_variables(content, page_title, navigation)
+    def assign_content_variables(content, page_title, navigation, raw_markdown)
       @content = content
       @page_title = page_title
       @sidebar_html = navigation[:sidebar_html] || ""
       @prev_next_html = navigation[:prev_next_html] || ""
       @toc = navigation[:toc] || []
       @breadcrumbs = navigation[:breadcrumbs]
-    end
-
-    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)
-    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
-    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_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}/")
+      @raw_markdown = raw_markdown
     end
 
     def assign_template_variables(template_options)
@@ -160,5 +166,27 @@ module Docyard
     def strip_md_from_links(html)
       html.gsub(/href="([^"]+)\.md"/, 'href="\1"')
     end
+
+    def assign_git_info(branding, file_path)
+      @show_edit_link = branding[:show_edit_link] && file_path
+      @show_last_updated = branding[:show_last_updated] && file_path
+      return unless @show_edit_link || @show_last_updated
+
+      git_info = Utils::GitInfo.new(
+        repo_url: branding[:repo_url],
+        branch: branding[:repo_branch],
+        edit_path: branding[:repo_edit_path]
+      )
+
+      @edit_url = git_info.edit_url(file_path) if @show_edit_link
+      @last_updated = git_info.last_updated(file_path) if @show_last_updated
+    end
+
+    def assign_feedback_variables
+      return unless config
+
+      @feedback_enabled = config.feedback.enabled
+      @feedback_question = config.feedback.question
+    end
   end
 end

data/lib/docyard/rendering/template_resolver.rb

@@ -117,6 +117,7 @@ module Docyard
         tagline: hero["tagline"],
         gradient: hero.fetch("gradient", true),
         image: symbolize_image(hero["image"]),
+        custom_visual: symbolize_custom_visual(hero["custom_visual"]),
         actions: symbolize_actions(hero["actions"])
       }.compact
     end
@@ -138,6 +139,19 @@ module Docyard
       end
     end
 
+    def symbolize_custom_visual(custom_visual)
+      return nil if custom_visual.nil?
+
+      if custom_visual.is_a?(String)
+        { html: custom_visual, placement: "side" }
+      elsif custom_visual.is_a?(Hash)
+        {
+          html: custom_visual["html"],
+          placement: custom_visual["placement"] || "side"
+        }
+      end
+    end
+
     def symbolize_actions(actions)
       return nil unless actions.is_a?(Array)
 

data/lib/docyard/routing/fallback_resolver.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../utils/path_utils"
+
 module Docyard
   module Routing
     class FallbackResolver
@@ -29,9 +31,7 @@ module Docyard
       end
 
       def sanitize_path(request_path)
-        clean = request_path.to_s.delete_prefix("/").delete_suffix("/")
-        clean = "index" if clean.empty?
-        clean.delete_suffix(".md")
+        Utils::PathUtils.sanitize_url_path(request_path)
       end
 
       def find_first_item_in_section(request_path)

data/lib/docyard/search/build_indexer.rb

@@ -63,11 +63,11 @@ module Docyard
       end
 
       def log(message)
-        puts message
+        Docyard.logger.info(message)
       end
 
       def log_warning(message)
-        warn message
+        Docyard.logger.warn(message)
       end
     end
   end