Description
Currently links in gleam.toml have to be full URLs with a protocol. It is nice that we validate their syntax, but it means that you cannot use relative links, which @oderwat has a use-case for.
Should we disable the validation entirely and let the programmer be responsible for checking these issues?
I think we should prevent packages with relative links from being published to Hex, as those links would not be valid on HexDocs.
Discussed in https://github.com/gleam-lang/gleam/discussions/4768
Originally posted by oderwat July 10, 2025 We need to build our own Gleam documentation server that works similarly to https://hexdocs.pm/, but builds documentation by accessing our private repositories containing private Gleam packages for our team's use.
The documentation updater clones the repositories and modifies the gleam.toml file to add back-links to the documentation server index. This is typically an HTTPS address for our documentation server, but when running locally, it's something like http://localhost:8000.
We attempted to add links = [{ title = "Home", href = "/index.html" }] to the gleam.toml file, but this doesn't work because the documentation builder validates that links have a valid scheme, throwing an error: uri without scheme for key 'links'....
Is this validation really necessary? It also prevents adding relative links within the documentation (including fragment identifiers using "#").
We could work around this by using a fixed URI and performing string replacement in the generated documentation, but this approach feels clunky and inelegant.