Georgios Pappas Jr 2025-05-11

🌒 super-link: Quarto/Pandoc filter to render links

Introduction

super-link is a Pandoc Pandoc Lua filter that transforms specially formatted Span or Citation elements in Markdown into hyperlinks using predefined configurations. Easily create links for services like Wikipedia, PubMed, DOI, GitHub, and more with simple markup.

---

Features ✨

• Convert spans/citations to links with preconfigured services
• Customize link text and URLs via span attributes
• Add new services via document metadata
• Supports both Markdown spans and Pandoc citations
• Automatic URL encoding and template handling

---

Formatting Spans ✏️

Spans in Pandoc Markdown are inline elements specified as: [text]{#id .class attribute=value}.

This filter recognizes specially formatted spans that include:

1. Mandatory ID: The span must have an ID of #l. This default ID name (l) can be changed by modifying the IDNAME variable in the Lua script.
2. Link Type: The type of link (which corresponds to a key in the LINKS configuration table) must be specified in one of two ways:
   • As a class name: The first class of the span is used as the link type. Example: [Albert_Einstein]{#l .wiki} (uses the wiki configuration).
   • As a type attribute: An attribute type specifies the link type. Example: [Albert_Einstein]{#l type=wiki} (also uses the wiki configuration).

The text inside the square brackets (e.g., “Albert_Einstein”) is used as the query string, which is typically appended to the base URL defined in the link’s configuration.

Predefined Link Types

The filter includes several predefined link types (keys in the LINKS table):

• wiki: Wikipedia article
• pubmed: PubMed article
• doi: DOI article/link
• github: GitHub repository/user
• githubsearch: GitHub search
• google: Google search
• duck: DuckDuckGo search
• youtube: YouTube video/channel
• YOUTUBE: YouTube search (uses a template, see below)

Examples

Markup	Resulting Link Text (approx.)	Resulting URL
[11111111]{#l .pubmed}	pubmed:11111111	https://pubmed.ncbi.nlm.nih.gov/11111111
[10.1155/2000/562159]{#l .doi}	DOI:10.1155/2000/562159	https://doi.org/10.1155/2000/562159
[pandoc-lua-filters]{#l .githubsearch}	pandoc-lua-filters	https://github.com/search?q=pandoc-lua-filters

Span Options for Customizing Link Appearance

You can customize the link’s displayed text using attributes on the span:

• title: Overrides the default link text (which is the query).
  • Markup: [11111111]{#l .pubmed title="Article to read"}
  • Result: A link to https://pubmed.ncbi.nlm.nih.gov/11111111 with the display text “pubmed:Article to read”.
• before and after: Add a prefix or suffix to the link’s display text. These override any before or after text defined in the global link configuration.
  • Markup: [Pandoc]{#l type=google before="🔍" after=" (search in Google)"}
  • Result: A link to https://www.google.com/search?q=Pandoc with the display text “🔍Pandoc (search in Google)”.
• template: The template for the URL. This is useful for links that require a specific format. The template can include %url% and %query% placeholders (don’t forget the %..%).
  • Markup: [pandoc-lua-filters]{#l .githubsearch template="https://github.com/search?q=%query%&type=repositories"}
  • Result: https://github.com/search?q=pandoc-lua-filters&type=repositories

Some link configurations (like duck) might already have before or after text defined. You can override these:

• [Pandoc]{#l .duck}
  • Result: Uses the default before text from the duck config (e.g., “🦆:Pandoc”).
• [Pandoc]{#l .duck before="Search" after=" (DuckDuckGo)"}
  • Result: Overrides defaults, display text becomes “SearchPandoc (DuckDuckGo)”.

Formatting Citations

The filter can also transform Pandoc’s citation syntax ([@key]) into links. The citation components are interpreted as follows:

• [prefix @key suffix]
  1. prefix (Text before @key): This is used as the query string for the URL (mandatory for the link to be useful).
  2. @key: This is the link type (e.g., @pubmed), corresponding to a key in the LINKS configuration (mandatory).
  3. suffix (Text after @key): This is used as the title (display text) for the link (optional; if omitted, the query (prefix) is used, potentially with before/after from config).

Examples

• Basic citation link:
  • Markup: [11111111 @pubmed]
  • Result: Equivalent to [11111111]{#l .pubmed}. Becomes a link to https://pubmed.ncbi.nlm.nih.gov/11111111 with text like “pubmed:11111111”.
• Citation link with a custom title:
  • Markup: [11111111 @pubmed Article to read]
  • Result: Becomes a link to https://pubmed.ncbi.nlm.nih.gov/11111111 with the display text “pubmed:Article to read”.

Note

For citations, the Span attributes (title, before and after) are not supported. The title appears directly in the citation markup, whereas before and after texts are taken from the configuration.

Customizing the links in the document metadata

You can add new link configurations or override existing ones directly in your Markdown/Quarto document’s YAML metadata block. The metadata key for these configurations is super-link by default, but this can be changed by modifying the FILTERNAME variable in the Lua script.

Each entry under super-link should be the name of the new (or overridden) link type, followed by either:

• A simple string (which will be taken as the url).
• A table defining url, and optionally before, after, encode, or template.

Example Metadata

---
author: Your Name
title: My Document
super-link:
  # New link with Simple URL string
  dockerhub: "https://hub.docker.com/search?q=" 
  # New link with more customizations
  mynewsite:
    url: "https://mynewsite.example.com/search?term="
    before: "Search MyNewSite: "
    encode: true
  # Override existing 'wiki' to not have 'before' text
  wiki:
    url: "https://pt.wikipedia.org/wiki"
    encode: true
    # 'before' and 'after' will be empty if not specified here
  # Create a new link based on a template
  luasearch:
    # Template for searching github repos in Lua language
    url: " https://github.com/search?q="
    template: "%url%%query%&type=repositories&l=Lua",
    before: "GitHub Lua repos for: "
    encode: true
---

Some text...

This is a link to `[my search term]{#l .mynewsite}`.

And another one: `[ubuntu @dockerhub Ubuntu Docker images]`

This would create several custom links:

dockerhub
a simple URL string to search in DockerHub

mynewsite
configuration for a new link type

wiki
Overrides the Wikipedia link to change the language (pt)

luasearch
Shows how to use a template to search a query in GitHub, filtering repositories in Lua language

---

Installation and execution 📦

Pandoc

Save the file super-link.lua in ~/.pandoc/filters (default directory for pandoc filters) or any other directory. Run using one of the following syntaxes:

pandoc -s test.md -t html -L super-link.lua
pandoc -s test.md -t html --lua-filter=super-link.lua
pandoc -s test.md -t html -L ~/myfilters/super-link.lua

The last alternative refers to the filter installed in a custom location.

Quarto

quarto install extension gpappasunb/super-link

Add the filter to the document metadata:

---
filters:
  - super-link.lua
---

Author

Prof. Georgios Pappas Jr
Computational Genomics group
University of Brasilia (UnB) - Brazil