Global Reference Style Links in Jekyll

Main Content

Now that I’m starting to blog more frequently¹, I’ve found myself wanting to link to common websites in my writing often. But looking up exact URLs and page titles (because I’m a perfectionist and I want the link title to match the page title) breaks me out of my writing pace. Having a common library of Markdown reference-style links would speed up my writing, reduce errors, and make me more likely to link where appropriate.

Is there an easy way to do it? Using the liquid include take, there is.²

Creating a Links Library

We start by creating a new markdown file in the includes directory. It can have any name, so long as the extension is .md³. Now simply start adding the markdown references tags, of the form:

[google]: https://google.com "Google"

As your link library grows, you’ll want to keep it organized. I use a one-level categorization, with each category alphabetized. I currently have the following categories in my links_library.md, although obviously everyone’s list will differ.

• Big Sites
• Coding Tools
• Cloud Platforms
• Jekyll/Octopress Related
• Programming Languages
• My Sites & Profiles (all refs prefixed by my-, e.g.: [my-github]:)

Now we simply include the links library at the end of every markdown document with the following code. If you use Octopress, you can add the links library to your templates.

[//]: # (Big Sites)
[github]: https://github.com "GitHub · Where software is built"
[google]: https://google.com "Google"

[//]: # (Coding Tools)
[atom]: https://atom.io
[asdf]: https://asdf-vm.com "Home | asdf"
[docker]: https://www.docker.com/ "Docker | Build, Ship, and Run Any App, Anywhere"
[rbenv]: https://github.com/rbenv/rbenv "Manage your app's Ruby environment"
[erlenv]: https://github.com/talentdeficit/erlenv "Simple erlang release management" 
[resty]: https://github.com/micha/resty "micha/resty"

[//]: # (Cloud Platforms)
[aws]: https://aws.amazon.com "Amazon Web Services (AWS) - Cloud Computing Services" 
[do]: https://www.digital-ocean.com "DigitalOcean: Simple Cloud Infrastructure for Developers"
[divshot]: https://divshot.io "Divshot | Static Web Hosting for Developers and Designers"
[heroku]: https://heroku.comi "Heroku | Cloud Application Platform"

[//]: # (Jekyll/Octopress Stuff)
[jekyll]: https://jekyllrb.com "Jekyll • Simple, blog-aware, static sites"
[hpstr]: https://github.com/mmistakes/hpstr-jekyll-theme "mmistakes/hpstr-jekyll-theme"
[markdown]: https://daringfireball.net/projects/markdown/syntax "Daring Fireball | Markdown Syntax Documentation"
[octopress]: https://octopress.org "Octopress"
[shiny-hpstr]: https://github.com/etothepiipower/shiny-hpstr "eToThePiIPower/shiny-hpstr"

[//]: # (My {Projects)}
[b4j]: https://github.com/eToThePiIPower/bootstrap4jekyll "GitHub - eToThePiIPower/Bootstrap4Jekyll"

Adding Comments

In order to keep all those categories nice and documented⁴, you should use some type of comments for documentation. Unfortunately, Markdown doesn’t support actual comments, but there’s a beautiful (ugly?) hack using reference links. Since the reference definitions don’t appear in the final processed documents, fake references can be used, inserting “comments” text where the title would normally go.

[//]: # (Here's a comment in Markdown)

Note that any text at all could be used for the reference text: I choose [//] because it’s a commonly used commenting syntax already. As for fake link, # works well because it’s a single character, a valid, null link, and again a commonly used commenting syntax.

Including By Default

In order to actually use the links library, the following liquid tag must be included somewhere in each post that uses a global reference link. Furthermore, to work with post excerpts (as on index pages), it must be part of the excerpt. You can make it part of the first paragraph (the default excerpt) by not adding a line between them.

{% include links_library.md %}
First text paragraph here, notice there is no blank line after `include`.

Unfortunately there is no way (as yet) to include the links library in a site-wide layout template for invisible inclusion in all posts. Octopress users, however, can take advantage of the templates stored in _templates/post, templates/page, etc.; along with the octopress new command we can generate new posts with the links library already added.

I’m hoping to include a well-stocked links library in Shiny HPSTR soon. In the meantime, I’ll leave with a link to his work-in-progress as an example:

[//]: # (Big Sites)
[github]: https://github.com "GitHub · Where software is built"
[google]: https://google.com "Google"
 
[//]: # (Coding Tools)
[atom]: https://atom.io
[resty]: https://github.com/micha/resty "micha/resty"
 
[//]: # (Cloud Platforms)
[divshot]: https://divshot.io "Divshot | Static Web Hosting for Developers and Designers"
[heroku]: https://heroku.comi "Heroku | Cloud Application Platform"
 
[//]: # (Jekyll/Octopress Stuff)
[jekyll]: https://jekyllrb.com "Jekyll • Simple, blog-aware, static sites"
[hpstr]: https://github.com/mmistakes/hpstr-jekyll-theme "mmistakes/hpstr-jekyll-theme"
[markdown]: https://daringfireball.net/projects/markdown/syntax "Daring Fireball | Markdown Syntax Documentation"
[octopress]: https://octopress.org "Octopress"
[shiny-hpstr]: https://github.com/etothepiipower/shiny-hpstr "eToThePiIPower/shiny-hpstr"
 
[//]: # (My Sites)
[my-github]: https://github.com/etothepiipower "eToThePiIPower (Charles Beynon)"