Anchor Links

Getting Headers to be Links in Bookdown

This summer I have been interning at RStudio on a project with Alison Hill, and I’ve been spending a lot of time getting to know bookdown and its friends. In particular, I’ve been thinking about how to make bookdown content more easily shared and accessible.

I’ve noticed that some markdown files within R have built-in ways to get a link to point to specific section headings. These are called anchor links. For example, what you see here:

Having these in a site is useful whenever you want to share a specific section with someone–and you’d like to send them a link that takes them to precisely the section you intend.

But in bookdown, there’s no built-in way to create anchor links with an icon for each section header. The closest you can get is to right-click on the header within the table of contents (TOC) and copy its URL address. But sometimes the subsection you want to link to doesn’t appear in the TOC, and you’re out of luck.

Yihui mentions in his blog how he uses a javascript trick to add this feature in. I thought I would build on this with a short tutorial to walk you through how to do this in bookdown.

If you want to make linking to sections a little easier for yourself and for your bookdown site users, then follow the steps below to create your own anchor links for bookdown section headers.

If you’re not viewing this on a tablet or mobile, here’s what the final product will look like:

Doing this will require:

  1. A wee bit of javascript in a .js file (–“but I know nothing about javascript!” you say?–don’t worry, you don’t need to. Copy/paste is all you need).

  2. An HTML file if you don’t already have one for your book.

  3. CSS

  4. Editing _output.yml

Adding all this in is a little bit like wrapping a present in a box, in a box, in another box… The javascript does the heavy lifting to make the links, but the javascript file has to be put in the HTML file, and the HTML file has to be referenced in the _output.yml file. And bookdown then uses the _output.yml file to implement the javascript code and link to the CSS that styles the anchors.

Let’s get started!

You can add anchor links to any book that you’ve already started.

I’m going to demo this starting from a skeletal book, using only the files that are created when you have a brand new R Project and have run the line of code below. If you already have a book, then skip to the next step.


After running this command, I commit to GitHub.

2) Embed book.js into HTML file

We’ll make an HTML file that will refer to our javascript file.

  1. File > New File > Text File

  2. Paste the line below into this file. Modify the path in quotes to point to your javascript file if yours is not in your working directory. (Note: This little line of code will be automatically injected within our bookdown’s existing <html> and <head> tags, when we later use includes: in_header:, so there’s no need to include these tags in this HTML file, but nothing bad will happen if you do).

    <script src="book.js"></script>
  3. Save this file as header.html in your project directory. You can choose a different name if you’d like.

Commit your HTML file to GitHub.

5) Preview your book

And enjoy your handywork!

View all my commits for this post here.

Final comments

When you’re developing your bookdown site, you can control what the section link url will be when you add, for example, {#mysection} to the end of your headers.1

The hashtag you choose here is what will get included in you anchor-linked url. So, it’s a good idea to choose shorter, simpler {#section} names than {#really-super-long-section-names-that-make-long-urls} to make sure your url don’t become unwieldy when it’s time to share.

Now you know everything you need to get started making anchor links for your bookdown books. If this post was useful to you, then give it a shout out on twitter. Have fun sharing links of your bookdown sections!!

  1. Read more about section header IDs in the bookdown book

Desirée De Leon
Desirée De Leon

My interests include illustration, neuroscience, and R.