all repos — h3rald @ bd311f8b8dc81e0210a670e0dc75be325d0ae7bc

The sources of https://h3rald.com

contents/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
-----
title: "Glyph – Links and Bookmarks"
content-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&#8217;t check if they are valid</li>
	<li>you can&#8217;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>=&gt;</code>) &#8212; 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>) &#8212; 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">&lt;p&gt;</span>This is a link to <span class="tag">&lt;a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">#test</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>test anchor<span class="tag">&lt;/a&gt;</span>.<span class="tag">&lt;/p&gt;</span>
<span class="line-numbers"><a href="#n2" name="n2">2</a></span><span class="tag">&lt;p&gt;</span>...<span class="tag">&lt;/p&gt;</span>
<span class="line-numbers"><a href="#n3" name="n3">3</a></span><span class="tag">&lt;p&gt;</span>This is <span class="tag">&lt;a</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">#wrong</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>#wrong<span class="tag">&lt;/a&gt;</span>.<span class="tag">&lt;/p&gt;</span>
<span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="tag">&lt;p&gt;</span>This is a <span class="tag">&lt;a</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">test</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>test anchor<span class="tag">&lt;/a&gt;</span>.<span class="tag">&lt;/p&gt;</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> -&gt; source: @: authoring.textile
<span class="line-numbers"><a href="#n3" name="n3">3</a></span> -&gt; 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&#8217;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>