Crosslinks link one part of your book to another part of your book.

There are two steps to making a crosslink:

  1. Give the thing you want to crosslink to an ID.
  2. Create a crosslink to that ID.

Quick Explanation

Crosslinks are just like other links in Markdown, except that instead of linking to a web page, you link to an ID name you’ve created.

So, if you want to link the words ‘a previous chapter’ to a chapter heading in your book, you would type something like:

As we discussed in [a previous chapter](#chapter-32)...

… if you have already assigned an ID name to the chapter heading, like this:

# Chapter 32 {#chapter-32}

The ID can be on the same line as a chapter or section header, like this:

# Chapter 32 {#chapter-32}

But it can’t be on a line of text. So, for example, this won’t work:

{#SirHDavyResults} Sir H. Davy, a British chemist

To make it work, the ID should be above the text, with no blank line between the ID and the text, like this:

{#SirHDavyResults}
Sir H. Davy, a British chemist

In order to crosslink to an image, you will need to use the following syntax:

{id="cat-picture"}
![A picture of a cat](images/cat.jpg)

Then crosslink to it like this:

Remember that [picture of a cat](#cat-picture)?

It’s important not to have any blank lines between the id and the image, and the image needs to be by itself on the line.

The exact same thing works for a code-block, you just need to add an id:

{id='something-amazing',line-numbers=off,lang=ruby}
~~~~~~
def something
  puts "something, something, something"
end
~~~~~~

Longer Explanation

To link from one word (or set of words) to another, you first need to identify the word (or words) you want to link to. To do that, you need to give the word you want to link to an ID name. The ID name will not be visible to the reader.

You can create an ID name by adding some text enclosed in { and }, plus a number sign #, like this:

{#IDname}

You can call the ID anything you like, which is why we just wrote ‘IDname’ in this example.

So, for example, if you want to link to the start of a chapter, you can add an ID to the line at the start of the chapter, like this:

# Chapter 32 {#chapter-32}

Crosslinking to something with an ID

Now that the item you are crosslinking to has an ID, you can link to it from anywhere in your text.

To do that, surround the word or words you want to turn into a link with [ and ], and then follow that with a section in ( and ) which includes the ID name you made up.

To complete the example, here’s what you would type if you wanted the words ‘a previous chapter’ to become a link to the ID {#chapter-32}:

As we discussed in [a previous chapter](#chapter-32)...

Here we give an ID of shopping-list to a list.

{#shopping-list}
* Bananas
* Cream
* Pie Crust

Make sure not to put the ID within an element, like a list or a code block, however. The ID should come before or after the element. So you can do this:

{#anchor}
- `test`

    abc

but not this:

- `test`
{#anchor}

    abc

Here are some further technical details:

This Markdown:

{#anchor}
- `test`

    abc

Produces this HTML (and similar LaTeX):

<ul id="anchor">
  <li><code>test</code>
    <p>abc</p>
  </li>
</ul>

Up next

Breaks