feat: update get_brand_color function support light/dark mode (#28)

Author: mcanouil

README.md

@@ -35,7 +35,7 @@ You can also use the shorter syntax ([v1.1.1](../../releases/tag/1.1.1)):
 
 Using colours from `_brand.yml` ([v1.1.0](../../releases/tag/1.1.0)):
 
-```markdown
+```yaml
 color:
   palette:
     red: "#b22222"
@@ -46,6 +46,39 @@ color:
 [Red]{colour="brand-color.red" bg-colour="brand-color.primary"}
 ```
 
+Using colours from light/dark themes with Quarto CLI >=1.7.28 ([v1.2.0](../../releases/tag/1.2.0)):
+
+- From document front matter:
+
+  ```yaml
+  brand:
+    light:
+      color:
+        palette:
+          fg: "#ffffff"
+          bg: "#b22222"
+    dark:
+      color:
+        palette:
+          fg: "#b22222"
+          bg: "#ffffff"
+  ```
+
+- From `_quarto.yml` and `_brand.yml` file
+
+  ```yaml
+  brand:
+    dark: _brand.yml
+  ```
+
+```markdown
+[Light: White/Red | Dark: Red/White]{colour="brand-color.fg" bg-colour="brand-color.bg"}
+```
+
+> [!NOTE]
+> Only the `html` support light/dark mode switching.
+> The other formats will use the light mode colours if available or the dark mode colours otherwise.
+
 ## Limitations
 
 LaTeX `\colorbox` command does not support wrapping/line breaks in the text to be highlighted.

_extensions/highlight-text/_extension.yml

@@ -1,7 +1,7 @@
 title: Highlight Text
 author: Mickaël Canouil
-version: 1.1.3
-quarto-required: ">=1.6.37"
+version: 1.2.0
+quarto-required: ">=1.7.28"
 contributes:
   filters:
     - highlight-text.lua

_extensions/highlight-text/highlight-text.lua

@@ -22,10 +22,14 @@
 # SOFTWARE.
 ]]
 
-local function get_brand_color(colour)
+--- Gets a colour value from brand theme or formats it for later use
+--- @param theme string The brand theme to use (light/dark)
+--- @param colour string The colour value or brand colour reference
+--- @return string The processed colour value
+local function get_brand_colour(theme, colour)
   local brand = require('modules/brand/brand')
   if colour and colour:match("^brand%-color.") then
-    colour = brand.get_color(colour:gsub("^brand%-color%.", ""))
+    colour = brand.get_color(theme, colour:gsub("^brand%-color%.", ""))
   else
     if FORMAT:match 'typst' and colour  ~= nil then
       colour = 'rgb("' .. colour .. '")'
@@ -34,28 +38,66 @@ local function get_brand_color(colour)
   return colour
 end
 
-local function highlight_html(span, colour, bg_colour)
-  if span.attributes['style'] == nil then
-    span.attributes['style'] = ''
-  elseif span.attributes['style']:sub(-1) ~= ";" then
-    span.attributes['style'] = span.attributes['style'] .. ";"
-  end
+--- Applies text and background colour styling for HTML-based outputs
+--- @param span table The span element to modify
+--- @param settings table The highlight settings containing colour and background colour
+--- @return table The modified span with HTML styling
+local function highlight_html(span, settings)
+  local result = {}
+  local theme_keys = {}
 
-  if colour ~= nil then
-    span.attributes['colour'] = nil
-    span.attributes['color'] = nil
-    span.attributes['style'] = span.attributes['style'] .. 'color: ' .. colour .. ';'
+  for key, _ in pairs(settings) do
+    table.insert(theme_keys, key)
   end
 
-  if bg_colour ~= nil then
-    span.attributes['bg-colour'] = nil
-    span.attributes['bg-color'] = nil
-    span.attributes['style'] = span.attributes['style'] .. 'border-radius: 0.2rem; padding: 0 0.2rem 0 0.2rem;' .. 'background-color: ' .. bg_colour .. ';'
+  for _, theme in ipairs(theme_keys) do
+    local theme_span = pandoc.Span(span.content)
+    local colour = settings[theme].colour
+    local bg_colour = settings[theme].bg_colour
+
+    for k, v in pairs(span.attributes) do
+      theme_span.attributes[k] = v
+    end
+
+    if theme_span.attributes['style'] == nil then
+      theme_span.attributes['style'] = ''
+    elseif theme_span.attributes['style']:sub(-1) ~= ";" then
+      theme_span.attributes['style'] = theme_span.attributes['style'] .. ";"
+    end
+
+    theme_span.classes = theme_span.classes or {}
+    table.insert(theme_span.classes, "quarto-highlight-text-" .. theme)
+
+    if colour ~= nil then
+      theme_span.attributes['colour'] = nil
+      theme_span.attributes['color'] = nil
+      theme_span.attributes['style'] = theme_span.attributes['style'] .. 'color: ' .. colour .. ';'
+    end
+
+    if bg_colour ~= nil then
+      theme_span.attributes['bg-colour'] = nil
+      theme_span.attributes['bg-color'] = nil
+      theme_span.attributes['style'] = theme_span.attributes['style'] ..
+        'border-radius: 0.2rem; padding: 0 0.2rem 0 0.2rem;' .. 'background-color: ' .. bg_colour .. ';'
+    end
+
+    table.insert(result, theme_span)
   end
 
-  return span
+  -- Return a single span or a list of spans
+  if #result == 1 then
+    return result[1]
+  else
+    return result
+  end
 end
 
+--- Applies text and background colour styling for LaTeX-based outputs
+--- @param span table The span element to modify
+--- @param colour string The text colour to apply
+--- @param bg_colour string The background colour to apply
+--- @param par boolean Whether to wrap in a paragraph box
+--- @return table The span content with LaTeX markup
 local function highlight_latex(span, colour, bg_colour, par)
   if colour == nil then
     colour_open = ''
@@ -86,6 +128,11 @@ local function highlight_latex(span, colour, bg_colour, par)
   return span.content
 end
 
+--- Applies text and background colour styling for Word documents
+--- @param span table The span element to modify
+--- @param colour string The text colour to apply
+--- @param bg_colour string The background colour to apply
+--- @return table The span content with OpenXML markup for Word
 local function highlight_openxml_docx(span, colour, bg_colour)
   local spec = '<w:r><w:rPr>'
   if bg_colour ~= nil then
@@ -102,6 +149,11 @@ local function highlight_openxml_docx(span, colour, bg_colour)
   return span.content
 end
 
+--- Applies text and background colour styling for PowerPoint presentations
+--- @param span table The span element to modify
+--- @param colour string The text colour to apply
+--- @param bg_colour string The background colour to apply
+--- @return table Raw inline containing OpenXML markup for PowerPoint
 local function highlight_openxml_pptx(span, colour, bg_colour)
   local spec = '<a:r><a:rPr dirty="0">'
   if colour ~= nil then
@@ -123,6 +175,11 @@ local function highlight_openxml_pptx(span, colour, bg_colour)
   return pandoc.RawInline('openxml', spec .. span_content_string .. '</a:t></a:r>')
 end
 
+--- Applies text and background colour styling for Typst output
+--- @param span table The span element to modify
+--- @param colour string The text colour to apply
+--- @param bg_colour string The background colour to apply
+--- @return table The span content with Typst markup
 local function highlight_typst(span, colour, bg_colour)
   if colour == nil then
     colour_open = ''
@@ -152,7 +209,11 @@ local function highlight_typst(span, colour, bg_colour)
   return span.content
 end
 
-function Span(span)
+--- Main filter function that processes span elements and applies highlighting
+--- based on the output format and specified attributes
+--- @param span table The span element from the document
+--- @return table The modified span or span content with appropriate styling
+local function highlight(span)
   local colour = span.attributes['fg']
   if colour == nil then
     colour = span.attributes['colour']
@@ -169,10 +230,31 @@ function Span(span)
     bg_colour = span.attributes['bg-color']
   end
 
-  if colour == nil and bg_colour == nil then return span end
+  local highlight_settings = {}
 
-  colour = get_brand_color(colour)
-  bg_colour = get_brand_color(bg_colour)
+  local modes = {"light", "dark"}
+  for _, mode in ipairs(modes) do
+    if quarto.brand.has_mode(mode) then
+      highlight_settings[mode] = {
+        colour = get_brand_colour(mode, colour),
+        bg_colour = get_brand_colour(mode, bg_colour)
+      }
+    end
+  end
+
+  if highlight_settings.light == nil and highlight_settings.dark == nil then
+    return span
+  end
+
+  if highlight_settings.light == nil then
+    highlight_settings.light = highlight_settings.dark
+  end
+
+  colour = highlight_settings.light.colour
+  bg_colour = highlight_settings.light.bg_colour
+
+  quarto.log.output(highlight_settings)
+  if colour == nil and bg_colour == nil then return span end
 
   if span.attributes['par'] == nil then
     par = false
@@ -182,7 +264,11 @@ function Span(span)
   end
 
   if FORMAT:match 'html' or FORMAT:match 'revealjs' then
-    return highlight_html(span, colour, bg_colour)
+    quarto.doc.add_html_dependency({
+      name = 'badge',
+      stylesheets = {"light-dark.css"}
+    })
+    return highlight_html(span, highlight_settings)
   elseif FORMAT:match 'latex' or FORMAT:match 'beamer' then
     return highlight_latex(span, colour, bg_colour, par)
   elseif FORMAT:match 'docx' then
@@ -195,3 +281,7 @@ function Span(span)
     return span
   end
 end
+
+return {
+  { Span = highlight },
+}

_extensions/highlight-text/light-dark.css

@@ -0,0 +1,9 @@
+body.quarto-light .quarto-highlight-text-light,
+body.quarto-dark .quarto-highlight-text-dark {
+  display: inline;
+}
+
+body.quarto-light .quarto-highlight-text-dark,
+body.quarto-dark .quarto-highlight-text-light {
+  display: none;
+}

example.qmd

@@ -31,11 +31,20 @@ execute:
 filters:
   - highlight-text
 brand:
-  color:
-    palette:
-      blue: "#0000ff"
-      red: "#b22222"
-    primary: "#ffffff"
+  light:
+    color:
+      palette:
+        fg: "#ffffff"
+        bg: "#b22222"
+      foreground: "#333333"
+      background: "#fafafa"
+  dark:
+    color:
+      palette:
+        fg: "#b22222"
+        bg: "#ffffff"
+      foreground: "#fafafa"
+      background: "#333333"
 ---
 
 This is a Quarto extension that allows to highlight text in a document for various format: HTML, LaTeX, Typst, and Docx.
@@ -127,20 +136,13 @@ Then you can use the span syntax markup to highlight text in your document.
 ## `_brand.yml`
 
 ```markdown
-[White text, Red background]{
-  colour="brand-color.primary" bg-colour="brand-color.red"
-}
-```
-
-[White text, Red background]{colour="brand-color.primary" bg-colour="brand-color.red"}
-
-```markdown
-[White text, Blue background]{
-  color="brand-color.primary" bg-color="brand-color.blue"
+[Light: White/Red | Dark: Red/White]{
+  colour="brand-color.fg"
+  bg-colour="brand-color.bg"
 }
 ```
 
-[White text, Blue background]{color="brand-color.primary" bg-color="brand-color.blue"}
+[Light: White/Red | Dark: Red/White]{colour="brand-color.fg" bg-colour="brand-color.bg"}
 
 ## Limitations