Repository navigation
stack haddock generates incorrect relative links #6863
Description
Overview
When running stack haddock in a project, the generated documentation uses incorrect relative links for re-exported packages in the index file. This seems to be caused by the wrong argument being given to the -i option when invoking Haddock.
Steps to reproduce
Create a trivial project, like so:
# stack.yaml
snapshot:
url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/24/34.yaml
packages:
- .
# package.yaml
dependencies:
- base
library:
source-dirs: lib
Then run stack haddock. Then open the documentation at file:///<project>/.stack-work/install/<platform>/<hash>/<ghc>/doc/all/index.html.
In it, all links to modules in base are incorrect. For instance, the link for Data.Eq points to doc/base-4.20.2.0-127e/Data-Eq.html. The base-4.20.2.0-127e folder does not exist, but base-4.20.2.0 does.
Running stack haddock --verbose reveals that the all documentation was generated with the following call to haddock (i have replaced parts of the path with $HOME and $PROJECT to try to make it a tiny bit less verbose, but it's still a lot, sorry):
$HOME/.ghcup/ghc/9.10.3/bin/haddock-ghc-9.10.3 \
--optghc=-package-db=$HOME/.stack/snapshots/x86_64-linux/8a23ab0f4c447aa1863c20e527e4f2aeeec2f0c3c2ab9fbe859c65d4c711ecc7/9.10.3/pkgdb \
--optghc=-package-db=$HOME/$PROJECT/.stack-work/install/x86_64-linux/8a23ab0f4c447aa1863c20e527e4f2aeeec2f0c3c2ab9fbe859c65d4c711ecc7/9.10.3/pkgdb \
--gen-contents \
--gen-index \
-i ../ghc-internal-9.1003.0-a65c,$HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/ghc-internal-9.1003.0-a65c/ghc-internal.haddock \
-i ../haddock-issue-0.0.0,$HOME/$PROJECT/.stack-work/install/x86_64-linux/8a23ab0f4c447aa1863c20e527e4f2aeeec2f0c3c2ab9fbe859c65d4c711ecc7/9.10.3/doc/haddock-issue-0.0.0/haddock-issue.haddock \
-i ../ghc-bignum-1.3-9ca9,$HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/ghc-bignum-1.3-9ca9/ghc-bignum.haddock \
-i ../base-4.20.2.0-127e,$HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/base-4.20.2.0-127e/base.haddock \
-i ../ghc-prim-0.12.0-d0f9,$HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/ghc-prim-0.12.0-d0f9/ghc-prim.haddock
The key element is that the argument to -i is incorrect. Note, for instance, that for base, the argument is as follows: -i ../base-4.20.2.0-127e,path/to/base.haddock. Re-running the command, but will the argument to -i changed to not include the prefix fixes all relative links in the generated documentation.
Stack version
$ stack --version
Version 3.9.3, Git revision c7eb8487a82d5c3e0b88d56f8b8a98be23223eb5 x86_64 hpack-0.39.1
Activity
nicuveo commentedon Mar 16, 2026
At a glance, it looks like the arguments to
-iare generated by iterating on a list of interfaces and checking that the directory exist; since the directory for, say,base, is indeed$HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/base-4.20.2.0-127e/base.haddock, which contains the suffix, that would explain how we end up with it in the option.A trivial fix would be to drop the version suffix right there, in
Stack.Build.Haddock, but this might just mask the underlying issue?mpilgrem commentedon Mar 16, 2026
@nicuveo, thanks for reporting. I need to investigate but I wonder if it is related to this GHC bug:
nicuveo commentedon Mar 16, 2026
ah, yeah, that seems likely, good catch!