unaltraweb 0.3.0

data/_plugins/code_blocks.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "rouge"
+
+module Unaltraweb
+  module CodeLexers
+    class Url < Rouge::RegexLexer
+      title "URL"
+      desc "URLs and decomposed query parameters"
+      tag "url"
+
+      state :root do
+        rule %r{https?://}, Keyword
+        rule %r{#[^\n]*}, Comment::Single
+        rule %r{[?&]}, Punctuation
+        rule %r{[A-Za-z_][\w.-]*(?==)}, Name::Attribute
+        rule %r{=}, Operator
+        rule %r{\b\d+(?:\.\d+)*\b}, Num
+        rule %r{[^#?&=\d]+}, Text
+        rule %r{.}, Text
+      end
+    end
+
+    class Spreadsheet < Rouge::RegexLexer
+      title "Spreadsheet formula"
+      desc "Spreadsheet formulas and cell references"
+      tag "spreadsheet"
+
+      state :root do
+        rule %r/\s+/, Text
+        rule %r/"(?:[^"]|"")*"/, Str
+        rule %r/\b(?:AND|AVERAGE|COUNTIF|DATEDIF|DATE|DAY|HEX2DEC|HLOOKUP|IF|ISBLANK|ISNUMBER|ISTEXT|LEFT|MID|MONTH|NA|NETWORKDAYS|ROUND|SI|SUM|SUMA|SUMIFS|TODAY|TRIM|VLOOKUP|WEEKDAY|XLOOKUP|YEAR)\b(?=\()/i, Name::Builtin
+        rule %r/[A-Za-z_][\w.-]*(?=!)/, Name::Namespace
+        rule %r/\$?[A-Z]{1,3}\$?\d+(?::\$?[A-Z]{1,3}\$?\d+)?/i, Name::Variable
+        rule %r/\d+(?:[.,]\d+)?/, Num
+        rule %r/[+\-*\/>=<&,:;!]/, Operator
+        rule %r/[()]/, Punctuation
+        rule %r/./, Text
+      end
+    end
+
+    class FileTree < Rouge::RegexLexer
+      title "File tree"
+      desc "Directory and file listings"
+      tag "filetree"
+
+      state :root do
+        rule %r/^(\s*)(.+?)(\/)(?=\n?$)/ do
+          groups Text, Name::Namespace, Punctuation
+        end
+        rule %r/^(\s*)(.+?)(\.[A-Za-z0-9]+)(?=\n?$)/ do
+          groups Text, Name::Variable, Name::Attribute
+        end
+        rule %r/\s+/, Text
+        rule %r/./, Text
+      end
+    end
+  end
+
+  module CodeBlocks
+    module_function
+
+    LANGUAGE_LABELS = {
+      "bash" => "Bash",
+      "c" => "C",
+      "console" => "Console",
+      "cpp" => "C++",
+      "csharp" => "C#",
+      "css" => "CSS",
+      "go" => "Go",
+      "haskell" => "Haskell",
+      "html" => "HTML",
+      "java" => "Java",
+      "javascript" => "JavaScript",
+      "js" => "JavaScript",
+      "json" => "JSON",
+      "julia" => "Julia",
+      "latex" => "LaTeX",
+      "markdown" => "Markdown",
+      "matlab" => "MATLAB",
+      "php" => "PHP",
+      "powershell" => "PowerShell",
+      "python" => "Python",
+      "r" => "R",
+      "ruby" => "Ruby",
+      "rust" => "Rust",
+      "shell" => "Shell",
+      "sh" => "Shell",
+      "sql" => "SQL",
+      "typescript" => "TypeScript",
+      "ts" => "TypeScript",
+      "xml" => "XML",
+      "yaml" => "YAML",
+      "yml" => "YAML"
+    }.freeze
+    SEMANTIC_LABELS = {
+      "url" => { "ca" => "URL", "es" => "URL", "en" => "URL" },
+      "spreadsheet" => { "ca" => "Fórmula", "es" => "Fórmula", "en" => "Formula" },
+      "filetree" => { "ca" => "Fitxers", "es" => "Archivos", "en" => "Files" }
+    }.freeze
+
+    def transform_html(html, site:, lang:)
+      source = html.to_s
+      return source unless source.match?(/<pre(?:\s|>)/i)
+
+      fragment = Nokogiri::HTML::DocumentFragment.parse(source)
+      fragment.css("div.highlighter-rouge").each do |wrapper|
+        decorate(wrapper, language_for(wrapper), lang)
+      end
+
+      fragment.css("pre > code").to_a.each do |code|
+        next if code.ancestors.any? { |ancestor| class_names(ancestor).include?("uw-code-block") }
+
+        wrap_standalone(code, lang)
+      end
+
+      fragment.to_html
+    end
+
+    def detect_lang(doc)
+      configured = doc.data["lang"].to_s
+      return normalize_lang(configured) unless configured.empty?
+
+      relative_path = doc.respond_to?(:relative_path) ? doc.relative_path.to_s : ""
+      path_lang = relative_path.tr("\\", "/").split("/")[1].to_s
+      fallback = doc.site.config["default_lang"] || doc.site.config["lang"] || "en"
+      normalize_lang(path_lang.empty? ? fallback : path_lang)
+    end
+
+    def normalize_lang(lang)
+      lang.to_s.downcase.split("-").first.to_s.then { |value| value.empty? ? "en" : value }
+    end
+
+    def decorate(wrapper, language, lang)
+      normalized_language = language.to_s.downcase
+      normalized_language = "text" if normalized_language.empty?
+
+      add_classes(wrapper, "uw-code-block", "language-#{normalized_language}")
+      wrapper["data-code-language"] = normalized_language
+      if LANGUAGE_LABELS.key?(normalized_language) || SEMANTIC_LABELS.key?(normalized_language)
+        label = display_label(normalized_language, lang)
+        replace_class(wrapper, "uw-code-verbatim", "uw-code-highlighted")
+        wrapper["role"] = "group"
+        wrapper["aria-label"] = label
+        add_header(wrapper, label)
+        ensure_line_numbers(wrapper)
+      else
+        replace_class(wrapper, "uw-code-highlighted", "uw-code-verbatim")
+        wrapper.remove_attribute("role")
+        wrapper.remove_attribute("aria-label")
+        wrapper.element_children.select { |child| class_names(child).include?("uw-code-header") }.each(&:remove)
+        remove_line_numbers(wrapper)
+      end
+    end
+
+    def wrap_standalone(code, lang)
+      source_pre = code.parent
+      language = language_for(code) || language_for(source_pre) || "text"
+      wrapper = node("div", code.document)
+      highlight = node("div", code.document)
+
+      wrapper["class"] = "highlighter-rouge"
+      highlight["class"] = "highlight"
+      source_pre.replace(wrapper)
+      wrapper.add_child(highlight)
+      highlight.add_child(source_pre)
+      decorate(wrapper, language, lang)
+    end
+
+    def add_header(wrapper, label)
+      return if wrapper.element_children.any? { |child| class_names(child).include?("uw-code-header") }
+
+      header = node("div", wrapper.document)
+      language = node("span", wrapper.document)
+      header["class"] = "uw-code-header"
+      language["class"] = "uw-code-language"
+      language.content = label
+      header.add_child(language)
+      wrapper.prepend_child(header)
+    end
+
+    def ensure_line_numbers(wrapper)
+      if (table = wrapper.at_css("table.rouge-table"))
+        mark_line_number_table(table)
+        return
+      end
+
+      code = wrapper.at_css(".highlight pre > code") || wrapper.at_css("pre > code")
+      return unless code
+
+      source_pre = code.parent
+      line_count = code.text.delete_suffix("\n").count("\n") + 1
+      table = line_number_table(code.document, line_count, source_pre, code)
+      source_pre.replace(table)
+    end
+
+    def remove_line_numbers(wrapper)
+      table = wrapper.at_css("table.rouge-table")
+      return unless table
+
+      source_pre = table.at_css("td.rouge-code > pre")
+      return unless source_pre
+
+      source_pre.unlink
+      table.replace(source_pre)
+    end
+
+    def line_number_table(document, line_count, source_pre, code)
+      table = node("table", document)
+      body = node("tbody", document)
+      row = node("tr", document)
+      gutter = node("td", document)
+      gutter_pre = node("pre", document)
+      code_cell = node("td", document)
+      code_pre = node("pre", document)
+
+      table["class"] = "rouge-table"
+      gutter["class"] = "rouge-gutter gl"
+      gutter_pre["class"] = "lineno"
+      gutter_pre.content = (1..line_count).to_a.join("\n") + "\n"
+      code_cell["class"] = "rouge-code"
+      code_pre["class"] = source_pre["class"].to_s
+
+      code.unlink
+      code_pre.add_child(code)
+      gutter.add_child(gutter_pre)
+      code_cell.add_child(code_pre)
+      row.add_child(gutter)
+      row.add_child(code_cell)
+      body.add_child(row)
+      table.add_child(body)
+      mark_line_number_table(table)
+      table
+    end
+
+    def mark_line_number_table(table)
+      table["role"] = "presentation"
+      table.css(".rouge-gutter, pre.lineno").each { |node| node["aria-hidden"] = "true" }
+    end
+
+    def language_for(node)
+      return nil unless node
+
+      language_class = class_names(node).find { |name| name.start_with?("language-") }
+      language_class&.delete_prefix("language-")
+    end
+
+    def display_label(language, lang)
+      labels = SEMANTIC_LABELS[language]
+      return labels[normalize_lang(lang)] || labels.fetch("en") if labels
+
+      LANGUAGE_LABELS.fetch(language)
+    end
+
+    def class_names(node)
+      node["class"].to_s.split
+    end
+
+    def add_classes(node, *classes)
+      node["class"] = (class_names(node) + classes).uniq.join(" ")
+    end
+
+    def replace_class(node, old_class, new_class)
+      node["class"] = ((class_names(node) - [old_class]) + [new_class]).uniq.join(" ")
+    end
+
+    def node(name, document)
+      Nokogiri::XML::Node.new(name, document)
+    end
+  end
+end
+
+Jekyll::Hooks.register %i[documents pages], :post_convert do |doc|
+  lang = Unaltraweb::CodeBlocks.detect_lang(doc)
+  doc.content = Unaltraweb::CodeBlocks.transform_html(doc.content, site: doc.site, lang: lang)
+end

data/_plugins/computation_figure_images.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+# Rewrites Markdown and HTML image references from executable computation
+# sources to their declared figure outputs. If an edited SVG exists for the
+# declared output, it wins over the generated one.
+#
+# Authoring model: a chapter references the compute source the same way it
+# references a diagram source:
+#
+#   ![Alt](assets/quarto/figures/boxplot.qmd "Caption"){: data-figure-width="48rem"}
+#
+# The plugin resolves the source, reads its `unaltraweb_compute.outputs`
+# (mode: figure), and rewrites the reference to the first declared output
+# (for example `assets/img/data-visualization/boxplot-housing.svg`). An edited
+# override named like the output with the extension replaced by `.edited.svg`
+# (for example `boxplot-housing.edited.svg`) is preferred and never overwritten.
+#
+# The plugin never renders: figures are produced by the host computation
+# pipeline (`make manual-compute-render`) before Jekyll runs.
+module Unaltraweb
+  module ComputationFigureImages
+    module_function
+
+    BASEURL_PREFIX = /\A\{\{\s*site\.baseurl\s*\}\}/.freeze
+    REMOTE_PATH_PREFIX = %r{\A(?:[a-z]+:)?//}i.freeze
+    FENCED_CODE_BLOCK = /^[ \t]*(`{3,}|~{3,})[^\n]*\n.*?^[ \t]*\1[ \t]*$/m.freeze
+    COMPUTE_SUFFIXES = %w[.qmd .rmd .r .py .ipynb].freeze
+    COMPUTE_SOURCE = /\.(?:qmd|rmd|ipynb|py|r)(?=[\s)"']|$)/i.freeze
+    MEDIA_SUFFIX = /\.(?:gif|jpeg|jpg|pdf|png|svg|webp)\z/i.freeze
+    EDITED_SUFFIX = ".edited.svg".freeze
+
+    def rewrite(content, site_source:)
+      return content if content.nil? || content.empty?
+
+      rewrite_outside_code_fences(content) { |chunk| rewrite_chunk(chunk, site_source: site_source) }
+    end
+
+    def rewrite_chunk(content, site_source:)
+      out = content.dup
+
+      out.gsub!(/!\[([^\]]*)\]\(([^)]*?#{COMPUTE_SOURCE})(\s+"[^"]*")?\)/i) do
+        alt = Regexp.last_match(1)
+        path = published_path_for(Regexp.last_match(2), site_source)
+        title = Regexp.last_match(3).to_s
+        "![#{alt}](#{path}#{title})"
+      end
+
+      out.gsub!(/(<img\b[^>]*\bsrc=)(["'])([^"']+?#{COMPUTE_SOURCE})\2/i) do
+        prefix = Regexp.last_match(1)
+        quote = Regexp.last_match(2)
+        path = published_path_for(Regexp.last_match(3), site_source)
+        "#{prefix}#{quote}#{path}#{quote}"
+      end
+
+      out
+    end
+
+    def rewrite_outside_code_fences(content)
+      source = content.to_s
+      fences = []
+      protected_source = source.gsub(FENCED_CODE_BLOCK) do
+        token = "UNALTRAWEBCOMPUTEFIGURECODE#{fences.length}"
+        fences << Regexp.last_match(0)
+        token
+      end
+
+      transformed = yield(protected_source)
+      fences.each_index.reverse_each do |index|
+        transformed.gsub!("UNALTRAWEBCOMPUTEFIGURECODE#{index}", fences[index])
+      end
+
+      transformed
+    end
+
+    def published_path_for(source_ref, site_source)
+      local = local_asset_path(source_ref, site_source)
+      unless local && File.file?(local)
+        raise Jekyll::Errors::FatalException, "Computed figure source not found: #{source_ref}. Verify the chapter reference and computation source_roots."
+      end
+
+      outputs = declared_outputs(local)
+      if outputs.empty?
+        warn_once("not-a-figure-#{local}", "Referenced compute source #{source_ref} declares no figure outputs (unaltraweb_compute.mode: figure, outputs); leaving the reference unchanged.")
+        return source_ref
+      end
+
+      output = outputs.first
+      edited = output.sub(MEDIA_SUFFIX, EDITED_SUFFIX)
+      edited_local = local_asset_path(edited, site_source)
+      if edited_local && File.file?(edited_local)
+        warn_when_edited_shadows_newer_source(local, output, edited_local, site_source)
+        return reference_for(source_ref, edited)
+      end
+
+      output_local = local_asset_path(output, site_source)
+      unless output_local && File.file?(output_local)
+        raise Jekyll::Errors::FatalException, "Missing rendered figure #{output} for #{source_ref}. Run `manual_computation_render` before building."
+      end
+
+      reference_for(source_ref, output)
+    end
+
+    def reference_for(source_ref, relative_path)
+      baseurl = source_ref[BASEURL_PREFIX]
+      return "#{baseurl}/#{relative_path}" if baseurl
+
+      return "/#{relative_path}" if source_ref.start_with?("/")
+
+      relative_path
+    end
+
+    def warn_when_edited_shadows_newer_source(source_local, output, edited_local, site_source)
+      return unless File.mtime(source_local) > File.mtime(edited_local)
+
+      warn_once(
+        "edited-figure-#{edited_local}",
+        "#{output.sub(MEDIA_SUFFIX, EDITED_SUFFIX)} exists and is older than #{relative_from(site_source, source_local)}; keeping the edited SVG. Ask before replacing it with a regenerated figure."
+      )
+    end
+
+    def relative_from(root, path)
+      root = File.expand_path(root)
+      expanded = File.expand_path(path)
+      return path unless expanded.start_with?("#{root}/")
+
+      expanded.delete_prefix("#{root}/")
+    end
+
+    def declared_outputs(source_local)
+      front = read_front_matter(source_local)
+      metadata = front.is_a?(Hash) ? front["unaltraweb_compute"] : nil
+      return [] unless metadata.is_a?(Hash)
+
+      mode = metadata["mode"]
+      return [] unless mode.to_s.strip.downcase == "figure"
+
+      outputs = metadata["outputs"]
+      outputs = [metadata["output"]] if outputs.nil? && metadata["output"]
+      return [] unless outputs.is_a?(Array)
+
+      listed = outputs.map(&:to_s).map(&:strip).reject(&:empty?)
+      listed.select { |path| path.match?(MEDIA_SUFFIX) && valid_relative_path?(path) }
+    end
+
+    def valid_relative_path?(path)
+      relative = Pathname.new(path)
+      !relative.absolute? && !relative.each_filename.include?("..")
+    end
+
+    def read_front_matter(path)
+      suffix = File.extname(path.to_s).downcase
+      text = suffix == ".qmd" || suffix == ".rmd" ? yaml_front_matter(path) : script_front_matter(path)
+      return {} if text.empty?
+
+      YAML.safe_load(text)
+    rescue Psych::Exception
+      warn_once("invalid-front-matter-#{path}", "Unparseable front matter in #{path}; treating it as a non-figure computation source.")
+      {}
+    end
+
+    def yaml_front_matter(path)
+      match = /\A---\s*\n(.*?)\n---\s*\n?/m.match(File.read(path, encoding: "UTF-8"))
+      match ? match[1] : ""
+    end
+
+    def script_front_matter(path)
+      suffix = File.extname(path.to_s).downcase
+      if suffix == ".ipynb"
+        return ipynb_front_matter(path) rescue ""
+      end
+
+      prefix = suffix == ".r" || suffix == ".rmd" ? "#'" : "#"
+      marker = "#{prefix} ---"
+      active = false
+      block = []
+      File.readlines(path, encoding: "UTF-8").each do |line|
+        if line.strip == marker
+          if active
+            return block.join("\n")
+          end
+          active = true
+          next
+        end
+        block << line.delete_prefix(prefix).sub(/\A /, "") if active
+      end
+      ""
+    end
+
+    def ipynb_front_matter(path)
+      notebook = JSON.parse(File.read(path, encoding: "UTF-8"))
+      metadata = notebook["metadata"]
+      if metadata.is_a?(Hash) && metadata["unaltraweb_front_matter"].is_a?(Hash)
+        return YAML.dump(metadata["unaltraweb_front_matter"])
+      end
+      cells = notebook["cells"] || []
+      cells.each do |cell|
+        next unless cell["cell_type"] == "markdown" || cell["cell_type"] == "raw"
+
+        source = cell["source"]
+        text = source.is_a?(Array) ? source.join : source.to_s
+        match = /\A---\s*\n(.*?)\n---\s*\n?/m.match(text)
+        return match[1] if match
+        break
+      end
+      ""
+    end
+
+    def local_asset_exists?(asset_path, site_source)
+      local = local_asset_path(asset_path, site_source)
+      local && File.file?(local)
+    end
+
+    def local_asset_path(asset_path, site_source)
+      local_path = asset_path
+        .sub(BASEURL_PREFIX, "")
+        .split(/[?#]/, 2)
+        .first.to_s
+        .sub(%r{\A/+}, "")
+
+      return nil if local_path.empty? || local_path.match?(REMOTE_PATH_PREFIX)
+
+      root = File.expand_path(site_source)
+      path = File.expand_path(local_path, root)
+      return nil unless path == root || path.start_with?("#{root}/")
+
+      path
+    end
+
+    def warn_once(key, message)
+      @warnings ||= {}
+      return if @warnings[key]
+
+      @warnings[key] = true
+      if defined?(Jekyll) && Jekyll.respond_to?(:logger)
+        Jekyll.logger.warn("unaltraweb-computations:", message)
+      else
+        warn("unaltraweb-computations: #{message}")
+      end
+    end
+  end
+end
+
+if defined?(Jekyll::Hooks)
+  Jekyll::Hooks.register :site, :post_read do |site|
+    # Reject generated figure outputs from static files when an edited SVG
+    # override exists, so only the authored figure is published.
+    site.static_files.reject! do |file|
+      relative = file.relative_path.to_s
+      next false if relative.empty?
+      next false unless relative.match?(Unaltraweb::ComputationFigureImages::MEDIA_SUFFIX)
+
+      edited = relative.sub(Unaltraweb::ComputationFigureImages::MEDIA_SUFFIX, Unaltraweb::ComputationFigureImages::EDITED_SUFFIX)
+      local = Unaltraweb::ComputationFigureImages.local_asset_path(edited, site.source)
+      local && File.file?(local)
+    end
+  end
+end
+
+Jekyll::Hooks.register [:documents, :pages], :pre_render do |doc|
+  next unless doc.respond_to?(:content) && doc.content
+
+  doc.content = Unaltraweb::ComputationFigureImages.rewrite(doc.content, site_source: doc.site.source)
+end if defined?(Jekyll::Hooks)

data/_plugins/computation_sources.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Unaltraweb
+  module ComputationSources
+    SUFFIXES = %w[.qmd .rmd .r .py .ipynb].freeze
+
+    def self.source_roots(site)
+      config_path = File.join(site.source, ".unaltraweb", "computations.yml")
+      config = File.file?(config_path) ? YAML.safe_load_file(config_path, aliases: false) : {}
+      roots = config.is_a?(Hash) ? config.fetch("source_roots", ["_chapters"]) : ["_chapters"]
+      Array(roots).map do |root|
+        path = Pathname.new(root.to_s)
+        value = path.cleanpath.to_s.downcase
+        if path.absolute? || value.empty? || value == "." || value.split("/").include?("..")
+          raise Jekyll::Errors::FatalException, "Invalid computation source root: #{root}"
+        end
+        "/#{value}/"
+      end
+    rescue Psych::Exception => e
+      raise Jekyll::Errors::FatalException, "Invalid .unaltraweb/computations.yml: #{e.message}"
+    end
+
+    Jekyll::Hooks.register :site, :post_read do |site|
+      roots = source_roots(site)
+      site.static_files.reject! do |file|
+        relative = file.relative_path.to_s.downcase
+        relative.start_with?("/.unaltraweb/") ||
+          (roots.any? { |root| relative.start_with?(root) } &&
+            (relative.include?("/.quarto/") || relative.end_with?(".quarto_ipynb") || SUFFIXES.any? { |suffix| relative.end_with?(suffix) }))
+      end
+
+      site.collections.each_value do |collection|
+        collection.docs.reject! do |document|
+          SUFFIXES.include?(File.extname(document.path).downcase)
+        end
+      end
+    end
+  end
+end