feat: render footnote text using superscripts

## Details

Request: #241

When the contents of a link starts with the ^ symbol we'll now assume
this is related to a footnote. When the footnote pattern is spotted we
replace the link contents with a superscript equivalent when possible.
There are some interesting gaps in the superscript glyphs, I do not know
why they exist, but they exist for parens, 0-9, most of a-z, and also
most of A-Z but both character sets have at least one missing glyph.

This behavior can be disabled by setting `link.footnote.superscript` to `false`.

Since the translation between base character and superscript is not
based on a shared offset or anything easy like that we maintain a
complete mapping of base character to superscript. If there are any
missing characters in the mapping then we skip doing any sort of
superscript rendering.

Author: MeanderingProgrammer

README.md

@@ -507,6 +507,11 @@ require('render-markdown').setup({
     link = {
         -- Turn on / off inline link icon rendering
         enabled = true,
+        -- How to handle footnote links, start with a '^'
+        footnote = {
+            -- Replace value with superscript equivalent
+            superscript = true,
+        },
         -- Inlined with 'image' elements
         image = '󰥶 ',
         -- Inlined with 'email_autolink' elements
@@ -1050,6 +1055,11 @@ require('render-markdown').setup({
     link = {
         -- Turn on / off inline link icon rendering
         enabled = true,
+        -- How to handle footnote links, start with a '^'
+        footnote = {
+            -- Replace value with superscript equivalent
+            superscript = true,
+        },
         -- Inlined with 'image' elements
         image = '󰥶 ',
         -- Inlined with 'email_autolink' elements

benches/readme_spec.lua

@@ -4,7 +4,7 @@ local util = require('benches.util')
 
 describe('README.md', function()
     it('default', function()
-        local base_marks = 100
+        local base_marks = 114
         util.less_than(util.setup('README.md'), 60)
         util.num_marks(base_marks)
 

doc/render-markdown.txt

@@ -554,6 +554,11 @@ Default Configuration ~
         link = {
             -- Turn on / off inline link icon rendering
             enabled = true,
+            -- How to handle footnote links, start with a '^'
+            footnote = {
+                -- Replace value with superscript equivalent
+                superscript = true,
+            },
             -- Inlined with 'image' elements
             image = '󰥶 ',
             -- Inlined with 'email_autolink' elements
@@ -1077,6 +1082,11 @@ Link Configuration ~
         link = {
             -- Turn on / off inline link icon rendering
             enabled = true,
+            -- How to handle footnote links, start with a '^'
+            footnote = {
+                -- Replace value with superscript equivalent
+                superscript = true,
+            },
             -- Inlined with 'image' elements
             image = '󰥶 ',
             -- Inlined with 'email_autolink' elements

lua/render-markdown/health.lua

@@ -4,7 +4,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '7.6.1'
+M.version = '7.6.2'
 
 function M.check()
     M.start('version')

lua/render-markdown/init.lua

@@ -54,8 +54,12 @@ local M = {}
 ---@field public icon? string
 ---@field public highlight? string
 
+---@class (exact) render.md.UserFootnote
+---@field public superscript? boolean
+
 ---@class (exact) render.md.UserLink
 ---@field public enabled? boolean
+---@field public footnote? render.md.UserFootnote
 ---@field public image? string
 ---@field public email? string
 ---@field public hyperlink? string
@@ -625,6 +629,11 @@ M.default_config = {
     link = {
         -- Turn on / off inline link icon rendering
         enabled = true,
+        -- How to handle footnote links, start with a '^'
+        footnote = {
+            -- Replace value with superscript equivalent
+            superscript = true,
+        },
         -- Inlined with 'image' elements
         image = '󰥶 ',
         -- Inlined with 'email_autolink' elements

lua/render-markdown/lib/converter.lua

@@ -0,0 +1,90 @@
+---@class render.md.Converter
+local M = {}
+
+---@private
+M.superscripts = {
+    [' '] = ' ',
+    ['('] = '⁽',
+    [')'] = '⁾',
+
+    ['0'] = '⁰',
+    ['1'] = '¹',
+    ['2'] = '²',
+    ['3'] = '³',
+    ['4'] = '⁴',
+    ['5'] = '⁵',
+    ['6'] = '⁶',
+    ['7'] = '⁷',
+    ['8'] = '⁸',
+    ['9'] = '⁹',
+
+    ['a'] = 'ᵃ',
+    ['b'] = 'ᵇ',
+    ['c'] = 'ᶜ',
+    ['d'] = 'ᵈ',
+    ['e'] = 'ᵉ',
+    ['f'] = 'ᶠ',
+    ['g'] = 'ᵍ',
+    ['h'] = 'ʰ',
+    ['i'] = 'ⁱ',
+    ['j'] = 'ʲ',
+    ['k'] = 'ᵏ',
+    ['l'] = 'ˡ',
+    ['m'] = 'ᵐ',
+    ['n'] = 'ⁿ',
+    ['o'] = 'ᵒ',
+    ['p'] = 'ᵖ',
+    ['q'] = nil,
+    ['r'] = 'ʳ',
+    ['s'] = 'ˢ',
+    ['t'] = 'ᵗ',
+    ['u'] = 'ᵘ',
+    ['v'] = 'ᵛ',
+    ['w'] = 'ʷ',
+    ['x'] = 'ˣ',
+    ['y'] = 'ʸ',
+    ['z'] = 'ᶻ',
+
+    ['A'] = 'ᴬ',
+    ['B'] = 'ᴮ',
+    ['C'] = nil,
+    ['D'] = 'ᴰ',
+    ['E'] = 'ᴱ',
+    ['F'] = nil,
+    ['G'] = 'ᴳ',
+    ['H'] = 'ᴴ',
+    ['I'] = 'ᴵ',
+    ['J'] = 'ᴶ',
+    ['K'] = 'ᴷ',
+    ['L'] = 'ᴸ',
+    ['M'] = 'ᴹ',
+    ['N'] = 'ᴺ',
+    ['O'] = 'ᴼ',
+    ['P'] = 'ᴾ',
+    ['Q'] = nil,
+    ['R'] = 'ᴿ',
+    ['S'] = nil,
+    ['T'] = 'ᵀ',
+    ['U'] = 'ᵁ',
+    ['V'] = 'ⱽ',
+    ['W'] = 'ᵂ',
+    ['X'] = nil,
+    ['Y'] = nil,
+    ['Z'] = nil,
+}
+
+---@param s string
+---@return string?
+function M.to_superscript(s)
+    local chars = {}
+    for char in s:gmatch('.') do
+        char = M.superscripts[char]
+        if char == nil then
+            return nil
+        end
+        table.insert(chars, char)
+    end
+    return table.concat(chars)
+end
+
+return M

lua/render-markdown/render/inline_highlight.lua

@@ -19,7 +19,7 @@ function Render:render()
     ---@type integer|nil
     local index = 1
     while index ~= nil do
-        local start_index, end_index = self.node.text:find('(=)=[^=]+=(=)', index)
+        local start_index, end_index = self.node.text:find('==[^=]+==', index)
         if start_index == nil or end_index == nil then
             index = nil
         else

lua/render-markdown/render/shortcut.lua

@@ -1,12 +1,15 @@
 local Base = require('render-markdown.render.base')
+local Converter = require('render-markdown.lib.converter')
 local Str = require('render-markdown.lib.str')
 
 ---@class render.md.render.Shortcut: render.md.Renderer
+---@field private link render.md.Link
 local Render = setmetatable({}, Base)
 Render.__index = Render
 
 ---@return boolean
 function Render:setup()
+    self.link = self.config.link
     return true
 end
 
@@ -28,6 +31,12 @@ function Render:render()
         self:wiki_link()
         return
     end
+
+    local _, _, text = self.node.text:find('^%[%^(.+)%]$')
+    if text ~= nil then
+        self:footnote(text)
+        return
+    end
 end
 
 ---@private
@@ -85,13 +94,13 @@ end
 
 ---@private
 function Render:wiki_link()
-    if not self.config.link.enabled then
+    if not self.link.enabled then
         return
     end
 
     local parts = Str.split(self.node.text:sub(2, -2), '|')
     local link_component = self:link_component(parts[1])
-    local icon, highlight = self.config.link.wiki.icon, self.config.link.wiki.highlight
+    local icon, highlight = self.link.wiki.icon, self.link.wiki.highlight
     if link_component ~= nil then
         icon, highlight = link_component.icon, link_component.highlight
     end
@@ -103,4 +112,23 @@ function Render:wiki_link()
     }, { 0, -1, 0, 1 })
 end
 
+---@private
+---@param text string
+function Render:footnote(text)
+    if not self.link.enabled or not self.link.footnote.superscript then
+        return
+    end
+
+    local value = Converter.to_superscript('(' .. text .. ')')
+    if value == nil then
+        return
+    end
+
+    self.marks:add_over('link', self.node, {
+        virt_text = { { value, self.link.highlight } },
+        virt_text_pos = 'inline',
+        conceal = '',
+    })
+end
+
 return Render

lua/render-markdown/state.lua

@@ -194,7 +194,6 @@ function M.validate()
             :nested('checkbox', function(checkbox)
                 checkbox
                     :type('enabled', 'boolean')
-                    :type('custom', 'table')
                     :one_of('position', { 'overlay', 'inline' })
                     :nested({ 'unchecked', 'checked' }, function(box)
                         box:type({ 'icon', 'highlight' }, 'string'):type('scope_highlight', { 'string', 'nil' }):check()
@@ -235,7 +234,9 @@ function M.validate()
             :nested('link', function(link)
                 link:type('enabled', 'boolean')
                     :type({ 'image', 'email', 'hyperlink', 'highlight' }, 'string')
-                    :type({ 'wiki', 'custom' }, 'table')
+                    :nested('footnote', function(footnote)
+                        footnote:type('superscript', 'boolean'):check()
+                    end)
                     :nested('wiki', function(wiki)
                         wiki:type({ 'icon', 'highlight' }, 'string'):check()
                     end)

lua/render-markdown/types.lua

@@ -41,8 +41,12 @@
 ---@field public icon string
 ---@field public highlight string
 
+---@class (exact) render.md.Footnote
+---@field public superscript boolean
+
 ---@class (exact) render.md.Link
 ---@field public enabled boolean
+---@field public footnote render.md.Footnote
 ---@field public image string
 ---@field public email string
 ---@field public hyperlink string

tests/ad_hoc_spec.lua

@@ -30,21 +30,21 @@ local function setext_heading(start_row, end_row, level)
 end
 
 ---@param row integer
----@param length integer
+---@param start_col integer
+---@param end_col integer
 ---@param link_text string
 ---@param highlight 'Link'|'UncycloLink'
 ---@param conceal string?
----@return render.md.MarkInfo[]
-local function bullet_link(row, length, link_text, highlight, conceal)
+---@return render.md.MarkInfo
+local function link(row, start_col, end_col, link_text, highlight, conceal)
     ---@type render.md.MarkInfo
-    local link = {
+    return {
         row = { row, row },
-        col = { 2, 2 + length },
+        col = { start_col, end_col },
         virt_text = { { link_text, util.hl(highlight) } },
         virt_text_pos = 'inline',
         conceal = conceal,
     }
-    return { util.bullet(row, 0, 1), link }
 end
 
 describe('ad_hoc.md', function()
@@ -63,12 +63,32 @@ describe('ad_hoc.md', function()
 
         vim.list_extend(expected, setext_heading(row:increment(2), row:increment(2), 2))
 
+        vim.list_extend(expected, { util.bullet(row:increment(2), 0, 1) })
+
+        vim.list_extend(expected, {
+            util.bullet(row:increment(), 0, 1),
+            link(row:get(), 2, 15, '󱗖 Basic One', 'UncycloLink', ''),
+        })
+
+        vim.list_extend(expected, {
+            util.bullet(row:increment(), 0, 1),
+            link(row:get(), 2, 25, '󱗖 With Alias', 'UncycloLink', ''),
+        })
+
+        vim.list_extend(expected, {
+            util.bullet(row:increment(), 0, 1),
+            link(row:get(), 2, 20, '󰀓 [email protected]', 'Link', ''),
+        })
+
+        vim.list_extend(expected, {
+            util.bullet(row:increment(), 0, 1),
+            link(row:get(), 2, 61, ' ', 'Link', nil),
+        })
+
         vim.list_extend(expected, {
-            util.bullet(row:increment(2), 0, 1),
-            bullet_link(row:increment(), 13, '󱗖 Basic One', 'UncycloLink', ''),
-            bullet_link(row:increment(), 23, '󱗖 With Alias', 'UncycloLink', ''),
-            bullet_link(row:increment(), 18, '󰀓 [email protected]', 'Link', ''),
-            bullet_link(row:increment(), 59, ' ', 'Link', nil),
+            util.bullet(row:increment(), 0, 1),
+            link(row:get(), 16, 25, '⁽¹ ᴵⁿᶠᵒ⁾', 'Link', ''),
+            link(row:increment(2), 0, 9, '⁽¹ ᴵⁿᶠᵒ⁾', 'Link', ''),
         })
 
         util.assert_view(expected, {
@@ -83,6 +103,9 @@ describe('ad_hoc.md', function()
             '    9 ● 󱗖 With Alias Something important',
             '   10 ● 󰀓 [email protected] Email',
             '   11 ●  Youtube Link',
+            '   12 ● Footnote Link ⁽¹ ᴵⁿᶠᵒ⁾',
+            '   13',
+            '   14 ⁽¹ ᴵⁿᶠᵒ⁾: Some Info',
         })
     end)
 end)

tests/data/ad_hoc.md

@@ -9,3 +9,6 @@ Heading 2 Line 2
 - [[Nickname|With Alias]] Something important
 - <[email protected]> Email
 - [Youtube Link](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
+- Footnote Link [^1 Info]
+
+[^1 Info]: Some Info