Skip to main content

Raymii.org Logo (IEC resistor symbol)logo

Quis custodiet ipsos custodes?
Home | About | All pages | RSS Feed | Gopher

Convert markdown inline links to reference style links with Pandoc

Published: 10-04-2019 | Author: Remy van Elst | Text only version of this article


Table of Contents


Markdown has two options to create a link. A link is the piece of text youclick to go to another webpage. Actually, three ways, since you can just embedHTML code in Markdown.

I write all the content for this site in Markdown files, which are thenconverted by my static site generator to HTML, text and a gopherversion. I'm used to using the inline link style, which is where you pastethe link right in the text. Since I've enabled the Gopher version of raymii.org,I noticed that there was no line wrapping.

The HTML website all arranges that via CSS, but the text-only Gopher does not.Sometimes Gopher clients wrap text, but most don't. I'm re-wrapping all articlesto make them fit, but the wrapping is way off with inline style markdown links.By converting them to reference style markdown links, the wrapping looks waybetter, and as an added bonus, reference style links give a better overview.

There are a few scripts floating around to convert these links, but either Rubyor NodeJS. It turns out after a bit of research that Pandoc, the anything-to-anything text conversion tool, has an option to use reference style links.With this option, I converted all the articles here (almost 400) to thereference style Markdown links.

If you like this article, consider sponsoring me by trying out a Digital OceanVPS. With this link you'll get $100 credit for 60 days). (referral link)

Markdown style links

In Markdown you can create links using two styles. The first is inline, itlooks like this:

[link title](https://url.tld/)

The second is reference style, it looks like this:

[link title][1]

Somewhere else in your document, you then have the referenced ID:

[1]: https://url.tld/

The ID can be anything, but for clearity I often use numbers.

Reference style links have the advantage that you can link multiple parts to thesame ID, instead of pasting the link multiple times.

With a long URL inline link, the text gets cluttered and, as in my case,wrapping fails.

Pandoc conversion

Pandoc is a tool to convert one markup language to another. It can for exampleconvert markdown to mediawiki syntax, or markdown to Word/OpenOffice, or viceversa. It can, in this usecase, also convert to the same format as you put in.This can be useful to change the wrapping or add a table of contents.

In this case it can convert inline style links to reference style links.

The following command will convert a markdown document to a markdown documentwith inline links, while not touching the wrapping.

pandoc --from markdown --to markdown --wrap=preserve --reference-links \  --output outputfile.md inputfile.md

A small annoyance is that the links are not referenced by a numeric ID.

This is an example document:

[inline_link1](https://raymii.org/s/)[Inline link 2](https://raymii.org)[Reference link 1 ][1][1]: http://raymii.org

This is the conversion result:

[inline\_link1][Inline link 2][Reference link 1]  [inline\_link1]: https://raymii.org/s/  [Inline link 2]: https://raymii.org  [Reference link 1]: http://raymii.org

Whereas I would do it manually like this:

[inline\_link1][1][Inline link 2][2][Reference link 1][3][1]: https://raymii.org/s/[2]: https://raymii.org[3]: http://raymii.org

Doesn't matter syntax wise, it will still be valid markdown, but since the goalwas to have the plain text version more readable, in my opinion this doesn'treally fit the bill.

Tags: articles, ingsoc, markdown, pandoc, raymiiorg, site, ubuntu