feat: add `hls-document-link-plugin` to support LSP document links by jetjinser · Pull Request #4898 · haskell/haskell-language-server

jetjinser · 2026-04-18T06:34:00Z

This PR introduces a new plugin hls-document-link-plugin that adds LSP documentLink support to Haskell Language Server.

This plugin automatically extracts documentation links for symbols in source code. These links are the same ones that power the [Documentation] link in the hover information.

Changes

New plugin: hls-document-link-plugin – extracts clickable links and provides them as document links. Editors can then open these links directly from the source code.
Configuration: Added documentLinkOn option to enable/disable the feature (default: True).

Usage

In Neovim 0.12 or later, you can place the cursor on the link and press gx to open it directly in your default browser.

The feature can be turned off by setting documentLinkOn: false in the HLS configuration.

Note. The getDocumentLinks helper for lsp-test is implemented manually here, but a same change is also pending in haskell/lsp#638. After that PR is merged and the dependency is updated, this part can be simplified.

fendor

Welcome back and happy to see you tackle this issue!

This looks pretty good to my cursory review. I have mostly nitpicks and a couple of clarification questions.
Other than that, LGTM :)

fendor · 2026-04-18T12:34:37Z

+      [ (SimilarDocumentLink
+          (DocumentLink (Range (Position 0 10) (Position 0 13))
+                               (Just (Uri "GHC-Types.html#t:Int"))
+                               Nothing
+                               Nothing)),


These could most likely benefit from some helpers. E.g.,:

Suggested change

[ (SimilarDocumentLink

(DocumentLink (Range (Position 0 10) (Position 0 13))

(Just (Uri "GHC-Types.html#t:Int"))

Nothing

Nothing)),

[ (SimilarDocumentLink (mkDocLink (mkRange 0 10 0 13) (Uri "GHC-Types.html#t:Int")),

Just a suggestion, feel free to ignore

fendor · 2026-04-18T12:35:12Z

+goldenTest :: TestName -> FilePath -> [SimilarDocumentLink] -> TestTree
+goldenTest title file expected = testCase title $ runWithDocumentLink filehs $ do


Not a golden test, right?

fendor · 2026-04-18T12:36:24Z

+-- custom Eq to ignore some details, such as specific URI
+-- not symmetry


Suggested change

-- custom Eq to ignore some details, such as specific URI

-- not symmetry

-- Custom Eq to ignore some details, such as specific URI.

-- This is not a lawful instance as it doesn't obey the `symmetry` law. Use at your own risk and only in tests.

fendor · 2026-04-18T12:37:35Z

+import Data.Maybe (fromJust, fromMaybe)
+f = (fromJust, fromMaybe)


Would this also work with constructors? E.g., Just or Nothing

fendor · 2026-04-18T12:37:59Z

+  pretty = \case {
+    LogShake shakeLog -> pretty shakeLog
+  }


Suggested change

pretty = \case {

LogShake shakeLog -> pretty shakeLog

}

pretty = \case

LogShake shakeLog -> pretty shakeLog

fendor · 2026-04-18T12:43:16Z

+  defineNoDiagnostics (cmapWithPrio LogShake recorder) $ \GetDocumentLinks nfp -> runMaybeT $ do
+    HAR {hieAst} <- useMT GetHieAst nfp
+    DKMap {getDocMap} <- useMT GetDocMap nfp
+    ast <- hoistMaybe $ getAsts hieAst Map.!? (HiePath . mkFastString . fromNormalizedFilePath) nfp


Suggested change

ast <- hoistMaybe $ getAsts hieAst Map.!? (HiePath . mkFastString . fromNormalizedFilePath) nfp

ast <- hoistMaybe $ getAsts hieAst Map.!? HiePath (mkFastString $ fromNormalizedFilePath nfp)

Just weird bracketing for my taste, feel free to ignore.

fendor · 2026-04-18T12:43:36Z

+    pure $ DocumentLinks (foldAst lookup ast)
+
+foldAst :: forall a t. Monoid a => ((Identifier, Span) -> a) -> HieAST t -> a
+foldAst lookup ast = case (nodeChildren ast) of


Suggested change

foldAst lookup ast = case (nodeChildren ast) of

foldAst lookup ast = case nodeChildren ast of

fendor · 2026-04-18T12:48:25Z

+foldAst :: forall a t. Monoid a => ((Identifier, Span) -> a) -> HieAST t -> a
+foldAst lookup ast = case (nodeChildren ast) of


Some docs would be nice, what is this folding over?

Added documentation.

This implementation is actually adapted from the Semantic Tokens plugin.

haskell-language-server/plugins/hls-semantic-tokens-plugin/src/Ide/Plugin/SemanticTokens/Tokenize.hs

Lines 80 to 85 in afc8779

-- | foldAst

-- visit every leaf node in the ast in depth first order

foldAst :: (Monad m) => HsSemanticLookup -> HieAST t -> Tokenizer m (DList (Range, HsSemanticTokenType))

foldAst lookupHsTokenType ast = if null (nodeChildren ast)

then liftMaybeM (visitLeafIds lookupHsTokenType ast)

else foldMapM (foldAst lookupHsTokenType) $ nodeChildren ast

fendor · 2026-04-18T12:59:05Z

Also, I am wondering whether this has any overlap with #4746 and the Documentation and Source links in the hover message?

fendor · 2026-04-18T13:05:03Z

Screencast_20260418_150352.webm

This is the behaviour on vscode... I suppose that's not the expected behaviour?

jetjinser · 2026-04-22T08:40:03Z

Also, I am wondering whether this has any overlap with #4746 and the Documentation and Source links in the hover message?

Yes. The links provided in this PR share the same source as the 'Documentation' links in the hover messages. The goal here is to expose that information through a more native and convenient LSP feature (DocumentLink).

Therefore, documentLink provides a local hackage link, not the online link provided in #4746.

jetjinser · 2026-04-22T09:01:37Z

Screencast_20260418_150352.webm

This is the behaviour on vscode... I suppose that's not the expected behaviour?

I’ve done some local testing and noticed the same behavior in VSCodium.

If I manually run xdg-open on the generated URI (e.g., file:///nix/store/.../docs/index.html#v:nodeChildren), it opens correctly in the external browser. This is also why gx works as expected in Neovim. It seems VSCodium's default behavior is to capture file:// URIs and render them in an internal webview/tab instead of passing them to the system handler?
Additionally, I found a minor UX conflict: when a DocumentLink is present, VSCodium's Ctrl+Click defaults to following the link, which "shadows" the Go to Definition action. This might cause some confusion?

EDIT:
For the first question,

    "workbench.externalUriOpeners": {
        "file:///*": "simpleBrowser.open"
    },

Ideally, this might work? However, I still couldn't get it to open in either an internal or external browser.

crtschin · 2026-04-22T10:51:26Z

However, I still couldn't get it to open in either an internal or external browser.

I think this might be a lsp consumer problem. I'm using Helix and by default all file:// links get opened by the editor as well, and only other links get the xdg-open treatment. I guess from an editor's pov, there is a legitimate usecase for opening html files in the editor.

I wonder, what's the hueristic nvim uses to determine whether to open files with xdg-open or locally in the editor?

jetjinser · 2026-04-22T12:14:27Z

I wonder, what's the hueristic nvim uses to determine whether to open files with xdg-open or locally in the editor?

Nvim doesn't attempt any heuristics.

It simply uses vim.ui.open, which always uses xdg-open (the equivalent command on other platforms).

https://github.com/neovim/neovim/blob/2ca31eddae0748de5d54207c2d34f7405fed4f29/runtime/lua/vim/_core/defaults.lua#L147-L181

It's possible that Neovim doesn't have a particular reason to open HTML, while a GUI editor does, and the former distinguishes between gx (opens ... using the system default handler) and gf (Edit the file ...). XX

vidit-od · 2026-04-22T14:21:50Z

Additionally, I found a minor UX conflict:

We also should take into consideration how to disable the underlines.
The by default view makes everything look too cluttered due to lots of underlines.

example :

jetjinser added 5 commits April 18, 2026 13:32

feat: add hls-document-link-plugin

1967271

test: hls-document-link-plugin golden test

7ee648a

feat: add documentLinkOn config

382b87a

test: update default-config

a8c3492

doc(features): support documentLink

0353713

jetjinser requested review from fendor and michaelpj as code owners April 18, 2026 06:34

jetjinser changed the title ~~feat: ddd hls-document-link-plugin to support LSP document links~~ feat: add hls-document-link-plugin to support LSP document links Apr 18, 2026

fendor requested review from crtschin, soulomoon and vidit-od April 18, 2026 12:32

fendor requested changes Apr 18, 2026

View reviewed changes

fendor added the status: needs review This PR is ready for review label Apr 18, 2026

jetjinser added 4 commits April 19, 2026 00:46

refactor: use mkDocLink to reduce template code

fbe109e

refactor(hls-document-link-plugin): not goldenTest

e644d72

test: more import test

93d2836

refactor: random improve

24826fc

		goldenTest :: TestName -> FilePath -> [SimilarDocumentLink] -> TestTree
		goldenTest title file expected = testCase title $ runWithDocumentLink filehs $ do

		-- custom Eq to ignore some details, such as specific URI
		-- not symmetry

		import Data.Maybe (fromJust, fromMaybe)
		f = (fromJust, fromMaybe)

	ast <- hoistMaybe $ getAsts hieAst Map.!? (HiePath . mkFastString . fromNormalizedFilePath) nfp
	ast <- hoistMaybe $ getAsts hieAst Map.!? HiePath (mkFastString $ fromNormalizedFilePath nfp)

	foldAst lookup ast = case (nodeChildren ast) of
	foldAst lookup ast = case nodeChildren ast of

		foldAst :: forall a t. Monoid a => ((Identifier, Span) -> a) -> HieAST t -> a
		foldAst lookup ast = case (nodeChildren ast) of

	-- \| foldAst
	-- visit every leaf node in the ast in depth first order
	foldAst :: (Monad m) => HsSemanticLookup -> HieAST t -> Tokenizer m (DList (Range, HsSemanticTokenType))
	foldAst lookupHsTokenType ast = if null (nodeChildren ast)
	then liftMaybeM (visitLeafIds lookupHsTokenType ast)
	else foldMapM (foldAst lookupHsTokenType) $ nodeChildren ast

Uh oh!

Conversation

jetjinser commented Apr 18, 2026

Changes

Usage

Uh oh!

fendor left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fendor commented Apr 18, 2026

Uh oh!

fendor commented Apr 18, 2026

Uh oh!

jetjinser commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jetjinser commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

crtschin commented Apr 22, 2026

Uh oh!

jetjinser commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vidit-od commented Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fendor left a comment •

edited

Loading

jetjinser commented Apr 22, 2026 •

edited

Loading

jetjinser commented Apr 22, 2026 •

edited

Loading

jetjinser commented Apr 22, 2026 •

edited

Loading