Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

## Unreleased
<!-- Add all new changes here. They will be moved under a version at release -->
* `FIX` Preserve fenced code blocks in hover documentation when resolving relative Markdown links [#3435](https://github.com/LuaLS/lua-language-server/issues/3435)

## 3.19.2
`2026-10-13`
Expand Down
80 changes: 59 additions & 21 deletions script/core/hover/description.lua
Original file line number Diff line number Diff line change
Expand Up @@ -87,8 +87,9 @@ end

---@param comment string
---@param suri uri
---@param context { fence: string? }
---@return string?
local function normalizeComment(comment, suri)
local function normalizeComment(comment, suri, context)
if not comment then
return nil
end
Expand All @@ -98,28 +99,63 @@ local function normalizeComment(comment, suri)
if comment:sub(1, 1) == '@' then
return nil
end
comment = comment:gsub('(%[.-%]%()(.-)(%))', function (left, path, right)
local scheme = furi.split(path)
if scheme
-- strange way to check `C:/xxx.lua`
and #scheme > 1 then
return
local function resolveLinks(prose)
return (prose:gsub('(%[.-%]%()(.-)(%))', function (left, path, right)
local scheme = furi.split(path)
if scheme
-- strange way to check `C:/xxx.lua`
and #scheme > 1 then
return
end
local absPath = ws.getAbsolutePath(suri:gsub('/[^/]+$', ''), path)
if not absPath then
return
end
local uri = furi.encode(absPath)
return left .. uri .. right
end))
end

local fence = context.fence
if not fence and not comment:find('[`~]') then
return resolveLinks(comment)
end

local parts = {}
local offset, segment = 1, 1
for line in util.eachLine(comment, true) do
local marker, rest = line:match('^ ? ? ?(```+)([^\r\n]*)')
if not marker then
marker, rest = line:match('^ ? ? ?(~~~+)([^\r\n]*)')
end
local absPath = ws.getAbsolutePath(suri:gsub('/[^/]+$', ''), path)
if not absPath then
return
if fence then
if marker and marker:sub(1, 1) == fence:sub(1, 1)
and #marker >= #fence and rest:match('^[ \t]*$') then
parts[#parts+1] = comment:sub(segment, offset + #line - 1)
segment = offset + #line
fence = nil
end
elseif marker and (marker:sub(1, 1) == '~' or not rest:find('`', 1, true)) then
-- CommonMark excludes backticks in backtick fence info strings to distinguish inline code.
parts[#parts+1] = resolveLinks(comment:sub(segment, offset - 1))
segment = offset
fence = marker
end
local uri = furi.encode(absPath)
return left .. uri .. right
end)
return comment
offset = offset + #line
end
-- A Markdown block can span several LuaDoc comments.
context.fence = fence
local tail = comment:sub(segment)
parts[#parts+1] = fence and tail or resolveLinks(tail)
return table.concat(parts)
end

local function getBindComment(source)
local uri = guide.getUri(source)
local lines = {}
local context = {}
for _, docComment in ipairs(source.bindComments) do
lines[#lines+1] = normalizeComment(docComment.comment.text, uri)
lines[#lines+1] = normalizeComment(docComment.comment.text, uri, context)
end
if not lines or #lines == 0 then
return nil
Expand Down Expand Up @@ -187,24 +223,25 @@ local function lookUpDocComments(source)
end
local uri = guide.getUri(source)
local lines = {}
local context = {}
for _, doc in ipairs(docGroup) do
if doc.type == 'doc.comment' then
lines[#lines+1] = normalizeComment(doc.comment.text, uri)
lines[#lines+1] = normalizeComment(doc.comment.text, uri, context)
elseif doc.type == 'doc.type'
or doc.type == 'doc.public'
or doc.type == 'doc.protected'
or doc.type == 'doc.private' then
if doc.comment then
lines[#lines+1] = normalizeComment(doc.comment.text, uri)
lines[#lines+1] = normalizeComment(doc.comment.text, uri, context)
end
elseif doc.type == 'doc.class' then
for _, docComment in ipairs(doc.bindComments) do
lines[#lines+1] = normalizeComment(docComment.comment.text, uri)
lines[#lines+1] = normalizeComment(docComment.comment.text, uri, context)
end
end
end
if source.comment then
lines[#lines+1] = normalizeComment(source.comment.text, uri)
lines[#lines+1] = normalizeComment(source.comment.text, uri, context)
end
lookUpDocSees(lines, docGroup)
if not lines or #lines == 0 then
Expand Down Expand Up @@ -330,7 +367,7 @@ local function tryDocFieldComment(source)
return
end
if source.comment then
return normalizeComment(source.comment.text, guide.getUri(source))
return normalizeComment(source.comment.text, guide.getUri(source), {})
end
if source.bindGroup then
return getBindComment(source)
Expand All @@ -353,9 +390,10 @@ local function getFunctionCommentMarkdown(source, raw)

local uri = guide.getUri(source)
local md = markdown()
local context = {}
for _, doc in ipairs(docGroup) do
if doc.type == 'doc.comment' then
local comment = normalizeComment(doc.comment.text, uri)
local comment = normalizeComment(doc.comment.text, uri, context)
md:add('md', comment)
elseif doc.type == 'doc.param' and not raw then
if doc.comment then
Expand Down
54 changes: 54 additions & 0 deletions test/crossfile/hover.lua
Original file line number Diff line number Diff line change
Expand Up @@ -1374,6 +1374,60 @@ local n: unknown
[here](file:///x.lua)]]
}

TEST {
{
path = 'a.lua',
content = ([[
--- [Before](before.md)
--- ```lua
--- ```%s
--- t[i](...)
--- ```
--- [`after`](after.md)
local function <?run?>() end
]]):format('\f')
},
hover = ([[
```lua
function run()
```

---

[Before](file:///before.md)
```lua
```%s
t[i](...)
```
[`after`](file:///after.md)]]):format('\f')
}

TEST {
{
path = 'a.lua',
content = [[
--- ~~~~lua
--- ~~~
--- t[i](...)
--- ~~~~
--- [guide](guide.md)
local <?run?>
]]
},
hover = [[
```lua
local run: unknown
```

---

~~~~lua
~~~
t[i](...)
~~~~
[guide](file:///guide.md)]]
}

TEST {
{
path = 'a.lua',
Expand Down
Loading