From 5e6d19106c19016eb32200999915246f5f10782d Mon Sep 17 00:00:00 2001
From: Kristijan Husak <husakkristijan@gmail.com>
Date: Tue, 15 Apr 2025 21:03:00 +0200
Subject: [PATCH] feat(links)!: allow granular highlighting of links

Previously, both link with and without description were highlighted only
with `@org.hyperlink` hl group, which was linked to `@markup.link.url`
by default.
Since Neovim also has `@markup.link` and `@markup.link.label` in
addition to `@markup.link.url`, use those hl groups accordingly.
1. `@org.hyperlink` for the non-important parts of link (square
brackets), and this hl group is now linked to `@markup.link`
2. `@org.hyperlink.url` for the actual url in the link. Hl group linked
to `@markup.link.url` by default
3. `@org.hyperlink.desc` for the link description. Hl group linked to
`@markup.link.label` by default

To return to the previous behavior, override `@org.hyperlink.url` and
`@org.hyperlink.desc` as suggested in the docs:

```
vim.api.nvim_create_autocmd('ColorScheme', {
  pattern = '*',
  callback = function()
    -- Define own colors
    vim.api.nvim_set_hl(0, '@org.hyperlink.url', { link = '@org.hyperlink' })
    vim.api.nvim_set_hl(0, '@org.hyperlink.desc', { link = '@org.hyperlink' })
  end
})
```
---
 docs/configuration.org            | 4 +++-
 lua/orgmode/colors/highlights.lua | 4 +++-
 queries/org/highlights.scm        | 4 ++--
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/configuration.org b/docs/configuration.org
index 89e41e785..3986701b4 100644
--- a/docs/configuration.org
+++ b/docs/configuration.org
@@ -2845,7 +2845,9 @@ The following highlight groups are used:
 - =@org.code.delimiter=: code text delimiter =~= - linked to =@markup.raw=,
 - =@org.verbatim=: =verbatim= text - linked to =@markup.raw=,
 - =@org.verbatim.delimiter=: verbatim text delimiter === - linked to =@markup.raw=,
-- =@org.hyperlink=: =[[file:link]]= text - linked to =@markup.link.url=,
+- =@org.hyperlink=: link without description (example: =[[file:/this/is/link]]=) - linked to =@markup.link=,
+- =@org.hyperlink.url=: Url part of the link with description (example: =[[file:/this/is/url][description]]=) - linked to =@markup.link.url=,
+- =@org.hyperlink.desc=: Description part of the link with description (example: =[[file:/path/to/file][description]]=) - linked to =@markup.link.label=,
 - =@org.latex=: Inline latex - linked to =@markup.math=,
 - =@org.table.delimiter= - =|= and =-= delimiters in tables - linked to =@punctuation.special=,
 - =@org.table.heading= - Table headings - linked to =@markup.heading=,
diff --git a/lua/orgmode/colors/highlights.lua b/lua/orgmode/colors/highlights.lua
index 8fe844b14..b9e4c1aab 100644
--- a/lua/orgmode/colors/highlights.lua
+++ b/lua/orgmode/colors/highlights.lua
@@ -61,7 +61,9 @@ function M.link_highlights()
     ['@org.code.delimiter'] = '@markup.raw',
     ['@org.verbatim'] = '@markup.raw',
     ['@org.verbatim.delimiter'] = '@markup.raw',
-    ['@org.hyperlink'] = '@markup.link.url',
+    ['@org.hyperlink'] = '@markup.link',
+    ['@org.hyperlink.url'] = '@markup.link.url',
+    ['@org.hyperlink.desc'] = '@markup.link.label',
     ['@org.latex'] = '@markup.math',
     ['@org.latex_env'] = '@markup.environment',
     ['@org.footnote'] = '@markup.link.url',
diff --git a/queries/org/highlights.scm b/queries/org/highlights.scm
index 5659ad438..aed641da2 100644
--- a/queries/org/highlights.scm
+++ b/queries/org/highlights.scm
@@ -43,8 +43,8 @@
 (table . (row (cell (contents) @org.table.heading)))
 (table (hr) @org.table.delimiter)
 (fndef label: (expr) @org.footnote (#offset! @org.footnote 0 -4 0 1))
-(link) @org.hyperlink
-(link_desc) @org.hyperlink
+(link url: (expr) @org.hyperlink.url) @org.hyperlink
+(link_desc url: (expr) @org.hyperlink.url desc: (expr) @org.hyperlink.desc) @org.hyperlink
 (link "[[" @_link_open "]]" @_link_close (#set! conceal ""))
 (link_desc "[[" @_link_open "][" @_link_separator "]]" @_link_close (#set! conceal ""))
 ((link_desc url: (expr)+ @_link_url (#set! @_link_url conceal "")) @_link (#set! @_link url @_link_url))