Over the last several months, I’ve been using Tableau to rebuild my long-neglected website. Tableau is part of the Elixir Tools project headed by @mhanberg, and is built on top of MDEx by @leandrocp. This library is one of ten libraries and Elixir extensions that I built. Most of these were built with the assistance of Kiro.

TableauRefLinkExtension is a Tableau extension that resolves “reference links” to pages, posts, and static assets without to know the precise URL of the referenced comments. This works with elements supporting the href or src attributes.

• Links: <a>, <link>
• Media: <img>, <audio>, <video>, <source>, <track>
• Embedded: <embed>, <iframe>, <script>

A reference link in this context is a partial link ($ref:<content-file> or $site:<path>) that is resolved against the content of the site with the configured base URL. I use this in my site for referencing my licence page ($ref:licence.md) so that if I move it from /licence to /about/licence it will be resolved correctly without having to find and resolve all locations.

Content Link Resolution ($ref:<content>)

Links with $ref:<content> resolve to content files (pages, posts) or static assets.

[My Post]($ref:_posts/2024-01-15-my-post.md)
[About Page]($ref:_pages/about.md)
![Logo]($ref:logo.png)
[With Anchor]($ref:post.md#section)

<a href="/posts/2024/01/15/my-post">My Post</a>
<a href="/about">About Page</a>
<img src="/logo.png" alt="Logo">
<a href="/posts/post#section">With Anchor</a>

If the content reference is just the filename (no /), files are searched across all content and static assets.

[My Post]($ref:my-post.md)

If the content reference is a path (contains /), the file paths are matched from the workspace root.

[Specific Post]($ref:_posts/2024-01-15-my-post.md) [Asset]($ref:images/logo.png)

$ref links are resolved from content before static assets. Missing references ($ref:no-file.md) become #ref-not-found:path with a logged warning. Ambiguous matches ($ref:one.md) use the first match with a logged warning.

Site Link Resolution ($site:<path>)

Links with $site:<path> resolve to files relative to the site base URL.

[Download PDF]($site:downloads/guide.pdf)
[Secret File]($site:secret/file.txt)

<a href="/base/downloads/guide.pdf">Download PDF</a>
<a href="/base/secret/file.txt">Secret File</a>

No content lookup or validation is performed.

• Hex
• Documentation
• Project Page

https://github.com/halostatue/tableau_ref_link_extension