Nathan McCoy Nathan McCoy - 2 months ago 21
Markdown Question

Jekyll unhide reference-style links on Github pages

I have been using github pages with

jekyll
for auto-generating my blog using
markdown
documents.

I would like to use reference-style links then show a list of the links at the bottom of the page.

basically, I want the reference-style links to be printed on the page, by default they are hidden.

The idea is to have a list of references that a reader can refer to for more information.

for example, the following text:

# some header
...some body text in the blog with a link to [wikipedia][1]
...
...
# reference links
[1]: https://www.wikipedia.org


should generate the following output:




some header



...some body text in the blog with a link to wikipedia
...
...

reference links



[1]: https://www.wikipedia.org




As seen, the reference-style link is used in the
markdown
but it is also displayed on the page.

The previous "correct" output was achieved by duplicating each line and escaping the special characters, but this seems a bit redundant.

Can this be achieved by changes to
_config.yml
or using
ruby
? Other options are also welcome (
css
magic?).

tldr; I want a way to "unhide" the reference-style links at the bottom of my
markdown
page.

Answer

First, you have to understand exactly what is doing what:

  • Your markdown parser is converting your markdown into html.
  • Jekyll is taking that html and organizing it into pages.
  • GitHub pages is serving up those html pages.
  • The client reads that html and executes any JavaScript, etc.

The problem is that the markdown parser doesn't include the reference links at the bottom of the page. It's not like they're there but hidden. They simply aren't there. So you aren't going to find a CSS solution, because there isn't anything to style. You might be able to accomplish this with a custom markdown parser that includes the reference links in the generated html, but that won't work with GitHub pages and is probably going to be pretty hackish.

Another option is to execute JavaScript that uses document.links to get every link on the page, then output them in a <ul> or something at the bottom of the page. Something like this:

var links = document.links;
for(var i = 0; i < links.length; i++) {
  var linkHref = document.createTextNode(links[i].href);
  var lineBreak = document.createElement("br");
  document.body.appendChild(linkHref);
  document.body.appendChild(lineBreak);
}

You might restrict that to only include links in a certain div (like this), that way you don't have to parse out your navigation links and whatnot. You also have to consider the order.

Another option might be to include them in each post's frontmatter as a yml list, then show those in the layout that displays the post.

Of course, you could also simply create the reference yourself using markdown.

Comments