# Troubleshooting missing hyperlinks on Hackage

**URL:** <https://discourse.haskell.org/t/troubleshooting-missing-hyperlinks-on-hackage/11611>\
**Category:** Uncategorized\
**Created:** [March 12, 2025, 1:51am UTC](https://discourse.haskell.org/t/troubleshooting-missing-hyperlinks-on-hackage/11611 "2025-03-12T01:51:31Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![jonathanknowles](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/jonathanknowles/32/1653_2.png) [@jonathanknowles](https://discourse.haskell.org/u/jonathanknowles)\
**Post date:** [March 12, 2025, 1:51am UTC](https://discourse.haskell.org/t/troubleshooting-missing-hyperlinks-on-hackage/11611/1 "2025-03-12T01:51:31Z")

</div>

I’m trying to troubleshoot **_missing hyperlinks_** in the documentation for:

- [`monoidmap-aeson`](https://hackage.haskell.org/package/monoidmap-aeson)
- [`monoidmap-quickcheck`](https://hackage.haskell.org/package/monoidmap-quickcheck)

Specifically, the Hackage docs for these packages **_lack hyperlinks_** to types and functions in the [`monoidmap`](https://hackage.haskell.org/package/monoidmap) package, such as [`MonoidMap`](https://hackage.haskell.org/package/monoidmap/docs/Data-MonoidMap.html#t:MonoidMap) or [`MonoidMap.fromMap`](https://hackage.haskell.org/package/monoidmap/docs/Data-MonoidMap.html#v:fromMap). Hyperlinks to types and functions in other packages are _unaffected_ – the problem seems specific to `monoidmap`. But when I build the same docs locally (with `cabal haddock`), hyperlinks to all packages (including `monoidmap`) are generated just fine! 😅

Compare the following docs for `Data.MonoidMap.Aeson` from `monoidmap-aeson`:

| Version | Built by | Hyperlinks generated to `monoidmap` on Hackage? |
| --- | --- | --- |
| [`jonathanknowles.github.io`](https://jonathanknowles.github.io/monoidmap-aeson/Data-MonoidMap-JSON.html) | `cabal haddock` in [GitHub Actions](https://github.com/jonathanknowles/monoidmap-aeson/actions/runs/13652263100/job/38163351639#step:11:1) | ✅ Yes |
| [`hackage.haskell.org`](https://hackage.haskell.org/package/monoidmap-aeson/docs/Data-MonoidMap-JSON.html) | Hackage | 💥 No |

Since this issue only happens on Hackage, I’d like to understand what’s different about how Hackage generates the documentation. I checked the [Hackage build logs](https://hackage.haskell.org/package/monoidmap-aeson-0.0.0.3/reports/1) for `monoidmap-aeson`, but all I see is this error (not sure if it’s relevant):

```haskell
Resolving dependencies...
Error: Internal libraries only supported with per-component builds.
Per-component builds were disabled because program coverage is enabled
In the package 'vector-0.13.2.0'

```

I’m curious:

1. Has anyone else encountered similar issues on Hackage, where links are generated to some packages but not to others?
2. Is it possible to access a more detailed build log for Haddock on Hackage to diagnose what’s happening?

When I run `cabal haddock` locally, I get a much more detailed log along with a coverage summary. For example: [GitHub Actions log](https://github.com/jonathanknowles/monoidmap-aeson/actions/runs/13652263100/job/38163351639#step:11:1).

Obviously, one workaround would be to manually upload documentation (with working hyperlinks) to Hackage, but I’d much rather fix the root of the problem.

If anyone has any insights to share, I’d be truly grateful—many thanks!

---

<div class="post-metadata">

**Author:** ![artem](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/artem/32/56_2.png) [@artem](https://discourse.haskell.org/u/artem)\
**Post date:** [March 12, 2025, 1:12pm UTC](https://discourse.haskell.org/t/troubleshooting-missing-hyperlinks-on-hackage/11611/2 "2025-03-12T13:12:39Z")

</div>

This is a known limitation of Hackage, sadly: [Re-exported modules in index are not linked · Issue #833 · haskell/hackage-server · GitHub](https://github.com/haskell/hackage-server/issues/833)

A workaround is to upload the docs manually.

---

<div class="post-metadata">

**Author:** ![jonathanknowles](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/jonathanknowles/32/1653_2.png) [@jonathanknowles](https://discourse.haskell.org/u/jonathanknowles)\
**Post date:** [March 13, 2025, 8:37am UTC](https://discourse.haskell.org/t/troubleshooting-missing-hyperlinks-on-hackage/11611/3 "2025-03-13T08:37:03Z")

</div>

> [@artem](#):
>
> This is a known limitation of Hackage, sadly: [Re-exported modules in index are not linked · Issue #833 · haskell/hackage-server · GitHub](https://github.com/haskell/hackage-server/issues/833)

@artem Thanks for your response!

I’m aware of that Hackage issue, but I don’t think it quite explains what I’m seeing.

As far as I can tell, I’m not re-exporting any _ **modules** _—I’m just trying to create very ordinary Haddock hyperlinks from package `a` to types and functions in the public API of package `b`.

The odd discrepancy I’m seeing in the docs for [`monoidmap-aeson`](https://hackage.haskell.org/package/monoidmap-aeson-0.0.0.3/docs/Data-MonoidMap-JSON.html):

- Hyperlinks _ **are** _ created to types and functions from packages like `aeson`.
- Hyperlinks are _ **not** _ created to types and functions from `monoidmap`.

Here’s a screenshot illustrating the issue—identifiers like `ToJSON`, `encode`, and `Sum` are hyperlinked, but `MonoidMap` and `fromList` are not:

 ![Screenshot from 2025-03-13 16-15-46](https://us1.discourse-cdn.com/flex002/uploads/haskell/original/2X/9/955616585547299a2801dd0b5d0b5adc0ef02d6a.png)

I initially suspected that I’d been using the wrong syntax. However, when I run `cabal haddock` locally, it runs without warnings and has no trouble generating hyperlinks. See: [Data.MonoidMap.JSON](https://jonathanknowles.github.io/monoidmap-aeson/Data-MonoidMap-JSON.html)

Since this behaviour is specific to Hackage, I’m really keen to understand what’s going wrong here, so I can try to fix it!

In particular, if there’s a way to access more detailed logs from Hackage, perhaps that might help get to the bottom of it. Any insights would be greatly appreciated!

---

<div class="post-metadata">

**Author:** ![artem](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/artem/32/56_2.png) [@artem](https://discourse.haskell.org/u/artem)\
**Post date:** [March 14, 2025, 1:22am UTC](https://discourse.haskell.org/t/troubleshooting-missing-hyperlinks-on-hackage/11611/4 "2025-03-14T01:22:10Z")

</div>

My bad, sorry. Is manual upload a viable workaround for you anyway?

---

<div class="post-metadata">

**Author:** ![Bodigrim](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/bodigrim/32/1457_2.png) [@Bodigrim](https://discourse.haskell.org/u/Bodigrim)\
**Post date:** [March 14, 2025, 1:55am UTC](https://discourse.haskell.org/t/troubleshooting-missing-hyperlinks-on-hackage/11611/5 "2025-03-14T01:55:28Z")

</div>

Hackage [uses](https://github.com/haskell/hackage-server/blob/1bb90f429b3bccba24402314497de4eba8336114/exes/BuildClient.hs#L780) `cabal v1-install --enable-documentation` to build Haddocks. However, `v1-` commands cannot quite cope with internal libraries, such as ones in `monoidmap` package, thus missing hyperlinks.

---

<div class="post-metadata">

**Author:** ![jonathanknowles](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/jonathanknowles/32/1653_2.png) [@jonathanknowles](https://discourse.haskell.org/u/jonathanknowles)\
**Post date:** [March 15, 2025, 12:30am UTC](https://discourse.haskell.org/t/troubleshooting-missing-hyperlinks-on-hackage/11611/6 "2025-03-15T00:30:51Z")

</div>

> [@artem](#):
>
> My bad, sorry.

No worries! It was a good opportunity for me to clarify the issue.  
Thank-you for commenting!

> [@artem](#):
>
> Is manual upload a viable workaround for you anyway?

As the author of various `monoidmap-*` packages, I could probably manage the ongoing cost of manually uploading their documentation.

However, this cost would potentially also affect any other packages depending on `monoidmap` that wish to have fully-hyperlinked docs on Hackage.

So I’m naturally keen to find a solution that doesn’t impose such a cost on downstream package authors!

---

<div class="post-metadata">

**Author:** ![jonathanknowles](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/jonathanknowles/32/1653_2.png) [@jonathanknowles](https://discourse.haskell.org/u/jonathanknowles)\
**Post date:** [March 15, 2025, 1:00am UTC](https://discourse.haskell.org/t/troubleshooting-missing-hyperlinks-on-hackage/11611/7 "2025-03-15T01:00:11Z")

</div>

> [@Bodigrim](#):
>
> Hackage [uses](https://github.com/haskell/hackage-server/blob/1bb90f429b3bccba24402314497de4eba8336114/exes/BuildClient.hs#L780) `cabal v1-install --enable-documentation` to build Haddocks. However, `v1-` commands cannot quite cope with internal libraries, such as ones in `monoidmap` package, thus missing hyperlinks.

Thanks @Bodigrim!

I guess one solution is to make `monoidmap-internal` (where core types and functions are defined) into a separate package, with its own independent PVP-compliant versioning.

Then [`monoidmap`](https://hackage.haskell.org/package/monoidmap) would have its responsibility reduced to just re-exporting _ **supported** _ types and functions.

I see this pattern is used by the [`bluefin`](https://hackage.haskell.org/package/bluefin) and [`bluefin-internal`](https://hackage.haskell.org/package/bluefin-internal) packages, with the latter using `{-# OPTIONS_HADDOCK not-home #-}` in its modules.

I guess the alternative is to wait for Hackage to upgrade to using `v2-` commands (or to contribute to the upgrade work). Though I’m guessing it’s a fairly non-trivial piece of work!