# Why documentation links are often broken?

**URL:** <https://discourse.julialang.org/t/why-documentation-links-are-often-broken/91903>\
**Category:** General Usage\
**Tags:** documentation\
**Created:** [December 20, 2022, 3:55pm UTC](https://discourse.julialang.org/t/why-documentation-links-are-often-broken/91903 "2022-12-20T15:55:17Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![rafael.guerra](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rafael.guerra/32/216610_2.png) [@rafael.guerra](https://discourse.julialang.org/u/rafael.guerra)\
**Post date:** [December 20, 2022, 3:55pm UTC](https://discourse.julialang.org/t/why-documentation-links-are-often-broken/91903/1 "2022-12-20T15:55:17Z")

</div>

It is quite common to find broken Julia package documentation links, like this one (see `docs stable` link in the page):

> **[GitHub - JuliaGraphics/Tk.jl: Julia interface to Tk windowing toolkit.](https://github.com/JuliaGraphics/Tk.jl)**
>
> Julia interface to Tk windowing toolkit. Contribute to JuliaGraphics/Tk.jl development by creating an account on GitHub.

Why is this and is there a workaround?

---

<div class="post-metadata">

**Author:** ![mbauman](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mbauman/32/31082_2.png) [@mbauman](https://discourse.julialang.org/u/mbauman)\
**Post date:** [December 20, 2022, 4:43pm UTC](https://discourse.julialang.org/t/why-documentation-links-are-often-broken/91903/2 "2022-12-20T16:43:40Z")

</div>

I don’t have an immediate fix or workaround, but here’s the why…

Creating documentation requires running code. Code that might break. And hosting the generated website somewhere. Hosting that might go away. Both things require some maintenance.

In this case, its docs are pointing at JuliaHub’s doc generation service: [JuliaHub](https://juliahub.com/ui/Packages/Tk/BVfq8/0.7.0)

If you click the little ⓘ button, you can get information about what happened when it tried to build. Clicking the logs shows:

```julia
┌ Error: `using Tk did not succeed.`
│ exception =
│ LoadError: InitError: Tk.TclError("error initializing Tk: no display name and no \$DISPLAY environment variable")
│ during initialization of module Tk
│ in expression starting at /juliateam/.julia/packages/Tk/c8ZUf/src/Tk.jl:94
└ @ DocumentationGenerator ~/.julia/packages/DocumentationGenerator/12evC/src/DocumentationGenerator.jl:33

```

In other words, Tk.jl doesn’t like running in a “headless” environment that is common to CI systems and doc building services.

---

<div class="post-metadata">

**Author:** ![oxinabox](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/oxinabox/32/206603_2.png) [@oxinabox](https://discourse.julialang.org/u/oxinabox)\
**Post date:** [December 20, 2022, 5:06pm UTC](https://discourse.julialang.org/t/why-documentation-links-are-often-broken/91903/3 "2022-12-20T17:06:28Z")

</div>

Not applicable in this case but  
a common reason docs are often broken is PkgTemplate.jl will insert doclinks for you  
but setting up docs to be hosted on github pages requires manual work of pushing keys.  
And it’s quite fiddly as you might mistakenly insert newlines etc (though DocumenterTools.jl tries as hard as possible to make it easy, and it definately makes it easier)  
So the default state of docs links on new packages is broken.

Older packages had docs working on TravisCI that broke when TravisCI went away

---

<div class="post-metadata">

**Author:** ![rafael.guerra](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rafael.guerra/32/216610_2.png) [@rafael.guerra](https://discourse.julialang.org/u/rafael.guerra)\
**Post date:** [December 20, 2022, 5:15pm UTC](https://discourse.julialang.org/t/why-documentation-links-are-often-broken/91903/4 "2022-12-20T17:15:09Z")

</div>

Thank you for your in-depth responses.  
Would it be a good idea to always create a backup pdf file? At least we would have something to chew…