epubjs
Version:
Render ePub documents in the browser, across many devices
55 lines (35 loc) • 4.4 kB
HTML
<html xmlns:epub="http://www.idpf.org/2007/ops" xmlns="http://www.w3.org/1999/xhtml"><head><title>Writing in the Editor</title><link rel="stylesheet" type="text/css" href="epub.css"/></head><body data-type="book"><section data-type="chapter" epub:type="chapter" data-pdf-bookmark="Chapter 5. Writing in the Editor"><div class="chapter" id="idm669472">
<section data-type="sect1" data-pdf-bookmark="Cross-References and Internal Links"><div class="sect1" id="crossreferences">
<h1>Cross-References and Internal Links</h1>
<p>A common component of many reference-type projects is <em>cross-references</em>: links from one part of a document to another. These links might point to a section just a few paragraphs away, but could also point to a location in a completely different file.</p>
<p>Atlas has built-in cross-reference support, though it does take a few steps, and some jumps over to the code editor. To add a cross-reference:</p>
<p>Add an <code>id</code> attribute to the element that you want to be the <em>destination</em> of the link. In the Code Editor, find the opening container tag for the section you are referencing (perhaps this is a <code><p></code> tag, or a <code><section></code> tag). Within that opening tag, add an <code>id</code> attribute with any name you like (something descriptive and memorable is porbably best--and remember not to use spaces in the <code>id</code> name!). For example:</p>
<pre data-original-title="" title="">
<p id="addingcrossrefs">Some text is here.</p></pre>
<p>Now go back to the place where you are adding the cross reference. Select the text that you want to turn into a link, and click the link button in the toolbar. In the dialog box that pops up, replace all the text with a “#” and then the <code>id</code> name that you created in the previous step, as shown in the following figure.</p>
<figure><div class="figure"><img alt="Alt Text" class="icontentsimagesaddxrefpng" src="assets/addxref.png"/> <h6><span class="label">Figure 5-4. </span>When creating a link to another section in your project, replace the link URL with the destination element’s id, preceded by a # sign.</h6></div></figure>
<p>Finally, switch over to the Code Editor, and find the link you just created. It should look something like this:</p>
<pre data-original-title="" title="">
<a href="#addingcrossrefs">document</a></pre>
<p>Inside the opening a tag, add this attribute, exactly as shown here: <code>data-type="xref"</code>. Your link should now look like this:</p>
<pre data-original-title="" data-type="programlisting" title="">
<a href="#addingcrossrefs" data-type="xref">document</a>
</pre>
<p>This <code>data-type</code> is the magic bit of code that tells Atlas to turn your link into a working cross reference when you build. You can move files and sections around while you’re writing, and Atlas will update the link when you build to make sure it points to the correct file in your project.</p>
<p>Atlas can also automatically generate link text for you, if you want. This is great for referencing chapter numbers or section titles that might change. Insert an empty <a> tag like this:</p>
<pre data-original-title="" data-type="programlisting" title="">
<a href="#addingcrossrefs" data-type="xref"></a>
</pre>
<p>And when you build, Atlas will automatically add the title of the section, or the chapter number, depending on what type of element you are referencing. For example, if you are pointing to a chapter, you would insert the following:</p>
<pre data-original-title="" data-type="programlisting" title="">
See the results in <a href="#chapterid" data-type="xref"></a>
</pre>
<p>And when you build, you’d see something like the following:</p>
<pre data-original-title="" data-type="programlisting" title="">
See the results in Chapter 4.</pre>
<div data-type="note" epub:type="note">
<p>For autogenerated link text, please place your <code>id</code> attributes on a section/block element (e.g., <code><section></code>, <code><figure></code>, <code><div></code>), and not on heading elements (<code><h1></code>-<code><h6></code>). This will ensure that link text is generated correctly.</p>
</div>
</div></section>
</div></section></body></html>