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.
Markdown style links
In Markdown you can create links using two styles. The first is inline, itlooks like this:
The second is reference style, it looks like this:
Somewhere else in your document, you then have the referenced ID:
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 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 ]: 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][Inline link 2][Reference link 1]: https://raymii.org/s/: https://raymii.org: 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