content/glyph/book/text_editing/links.html
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 |
----- permalink: links title: Glyph – Links and Bookmarks type: page ----- <nav class="navigation"><a href="/glyph/book/text_editing/topics.html">← Topics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/images.html">Images and Figures →</a></nav> <p>Lightweight markups let you create internal and external links in a very easy way, and you can still do so in Glyph. However, if you do so:</p> <ul> <li>you can’t check if they are valid</li> <li>you can’t infer the link title automatically</li> </ul> <p>If you care about link validation and you want to save some keystrokes, then you should use:</p> <ul> <li>the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro (aliased to <code>=></code>) — to create internal and external links.</li> <li>the <a href="/glyph/book/macros/macros_inline.html#m_anchor"><code>anchor</code></a> macro (aliased to <code>#</code>) — to create named anchors (bookmarks) within your document.</li> </ul> <aside class="box"> <div class="box-title">Example</div> <p> The following Glyph code: </p> <div class="CodeRay"> <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>This is a link to link[#test]. <span class="line-numbers"><a href="#n2" name="n2">2</a></span>... <span class="line-numbers"><a href="#n3" name="n3">3</a></span>This is link[#wrong]. <span class="line-numbers"><a href="#n4" name="n4">4</a></span>This is a #[test|test anchor].</pre></div> </div> <p> Is translated into the following HTML code: </p> <div class="CodeRay"> <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span><span class="tag"><p></span>This is a link to <span class="tag"><a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">"</span><span class="content">#test</span><span class="delimiter">"</span></span><span class="tag">></span>test anchor<span class="tag"></a></span>.<span class="tag"></p></span> <span class="line-numbers"><a href="#n2" name="n2">2</a></span><span class="tag"><p></span>...<span class="tag"></p></span> <span class="line-numbers"><a href="#n3" name="n3">3</a></span><span class="tag"><p></span>This is <span class="tag"><a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">"</span><span class="content">#wrong</span><span class="delimiter">"</span></span><span class="tag">></span>#wrong<span class="tag"></a></span>.<span class="tag"></p></span> <span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="tag"><p></span>This is a <span class="tag"><a</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">"</span><span class="content">test</span><span class="delimiter">"</span></span><span class="tag">></span>test anchor<span class="tag"></a></span>.<span class="tag"></p></span></pre></div> </div> <p>Additionally, the following warning message is displayed when <a href="/glyph/book/compiling/compiling.html#compile">compiling</a>:</p> <div class="CodeRay"> <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>warning: Bookmark 'wrong' does not exist <span class="line-numbers"><a href="#n2" name="n2">2</a></span> -> source: @: authoring.textile <span class="line-numbers"><a href="#n3" name="n3">3</a></span> -> path: document/body/bodymatter/chapter/@/textile/section/section/box/link</pre></div> </div> </aside> <p>Basically, if you use the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro and the <a href="/glyph/book/macros/macros_inline.html#m_anchor"><code>anchor</code></a> macro, Glyph makes sure that:</p> <ul> <li>all links point to valid anchors within the document (regardless if the anchors are before or after the link, in snippets or included files).</li> <li>there are no duplicate anchors within the documents.</li> <li>if no title is specified as second parameter for the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro, the anchor’s name is used as such.</li> </ul> <p>Besides using the <a href="/glyph/book/macros/macros_inline.html#m_anchor"><code>anchor</code></a> macro, you can also create an anchor for a header by passing an <code>@id</code> attribute the the <a href="/glyph/book/macros/macros_structure.html#m_section"><code>section</code></a> macro, like this:</p> <div class="CodeRay"> <div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>section[ <span class="line-numbers"><a href="#n2" name="n2">2</a></span> @title[My Section] <span class="line-numbers"><a href="#n3" name="n3">3</a></span> @id[my_section] <span class="line-numbers"><a href="#n4" name="n4">4</a></span>... <span class="line-numbers"><a href="#n5" name="n5">5</a></span>]</pre></div> </div> <p>By default, validation is only enabled for internal links (i.e. the check occurs if the first parameter of the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a> macro starts with a <code>#</code>). You can enable it for external links as well by setting the <a href="/glyph/book/config/options.html#s_options_url_validation"><code>options.url_validation</code></a> setting to <code>true</code>. If URL validation is enabled, an error is returned if a link returns an HTTP status greater than 302.</p> <aside class="important"> <span class="note-title">Important</span>Enabling URL validation may significantly slow down compilation if a lot of external links are present. </aside> <nav class="navigation"><a href="/glyph/book/text_editing/topics.html">← Topics</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/text_editing/images.html">Images and Figures →</a></nav> |