super links.py

Introduction

Pandoc filter that creates custom links from bracketed spans with a specific ID (#l), written as:

1. with a 'type' attribute

    [text]{#l type=wiki}
   

2. with a 'class' name starting with a dot

    [text]{#l .wiki}
   

The link text is specified inside the square brackets. Its URL is configured in the dictionary LINKS or in the markdown metadata (see later).

The keys of the LINKS dictionary contain the type or class name that will provide the URL mapping for the link. In the simpler case, there will be a string containing the URL. The final URL will be the URL in the dictionary appended by the text inside the brackets.

[text]{#l type=github}

URL => https://github.com/text

The default LINKS dict contains (showing only the github entry):

LINKS = {"github" : "https://github.com/"}

Changing the displayed text

If the attribute "title" is set, then it will replace the link text. The original text in brackets will still be used to create the link URL

[Arabidopsis_thaliana]{#l .wiki title="Thale cress"}
-> <p><a href="https://en.wikipedia.org/wiki/Arabidopsis_thaliana" class="wiki" title="Arabidopsis thaliana">Thale cress</a></p>

Also, the "before' and 'after' attributes can be used to preprend or append text to the link text

[Arabidopsis_thaliana]{#l .wiki title="Thale cress" before="wikipedia:"}
-> <p><a href="https://en.wikipedia.org/wiki/Arabidopsis_thaliana" class="wiki" title="Arabidopsis thaliana">wikipedia:Thale cress</a></p>

Specifying new link types

Aside from the default cases, additional links can be configured in the pandoc metadata header:

---
super-links:
    foo: "https://hello.co"
    other:
        url: "HTTP://foo.com/"
        encode: true
        before: "SOMETEXT:"
        after: " <--AFTER"

...

Any output format should be supported, and in the case above we will have the following results, using the HTML output format:

[FOO]{#l .foo}
-> <p><a href="https://hello.co/FOO" class="foo">FOO</a></p>

[Some text]{#l type=other}
-> <p><a href="HTTP://foo.com//Some+text" type="other">SOMETEXT:Some text&lt;–AFTER</a></p>

[1233211]{#l type=pubmed}
-> <p><a href="https://pubmed.ncbi.nlm.nih.gov//1233211" type="pubmed">pubmed:1233211</a></p>

[Arabidopsis_thaliana]{#l .wiki title="Arabidopsis thaliana" before="WIKI:"}
-> <p><a href="https://en.wikipedia.org/wiki//Arabidopsis_thaliana" class="wiki" title="Arabidopsis thaliana" data-before="WIKI:">WIKI:Arabidopsis thaliana</a></p>

[10.1007/978-1-4613-8850-0_3]{#l .doi}
-> <p><a href="https://doi.org//10.1007/978-1-4613-8850-0_3" class="doi">DOI:10.1007/978-1-4613-8850-0_3</a></p>

Advantages

This filter, in some cases, requires less typing to represent a link. For instance:

• Plain markdown

        ![thale cress](https://en.wikipedia.org/wiki/Arabidopsis_thaliana)
  

• With filter

        [Arabidopsis_thaliana]{#l .wiki}
  

Installation

1. Install python 3 (version >3.9) and pandoc

2. Install panflute python libraries

    pip3 install panflute
   

3. Download and place the file in directory:

    ~/.pandoc/filters
   

Usage in pandoc

   pandoc -s test.md  -t beamer --filter super-links.py

Author

Prof. Georgios Pappas Jr
University of Brasilia (UnB) - Brazil
version 0.1