all repos — h3rald @ b3442cd80d633f1412303de98a8301e8b8fd86c0

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
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
-----
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>