all repos — h3rald @ 6b243ded05a7593922d198634c681075de1c12e2

The sources of https://h3rald.com

contents/glyph/book/extending/layouts.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
 95
 96
 97
 98
 99
 100
 101
 102
 103
 104
 105
 
-----
title: "Glyph - Layouts"
content-type: page
-----
<nav class="navigation"><a href="/glyph/book/extending/interpreting.html">← Interpreting Glyph Code</a> | <a
		href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/further_reading.html">Further
		Reading →</a></nav>
<p>When generating <a href="/glyph/book/text_editing/topics.html#topics">topic</a>-based outputs, Glyph uses
	<em>layouts</em> to render topics as standalone documents. By default, the following two layout are used:</p>
<ul>
	<li><code>topic</code> &#8212; used to render standard topics.</li>
	<li><code>index</code> &#8212; used to render the index page of your document.</li>
</ul>
<p>Layouts are nothing more than &#8220;fancy&#8221; Glyph macros defined using the Glyph language (i.e. by using <a
		href="/glyph/book/extending/interpreting.html#rewriting">macro rewriting</a>) within a single
	<code>.glyph</code> file.</p>
<section class="section">
	<header>
		<h3 id="h_96" class="toc">Topic Layout</h1>
	</header>
	<p>The default layout used to render all web topics (the layout used for web5 topics is very similar) is defined as
		follows:</p>
	<div class="CodeRay">
		<div class="code">
			<pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>document[
<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>  head[
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>    style[default.css]
<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>  ]
<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>  body[
<span class="line-numbers"> <a href="#n6" name="n6">6</a></span>    @class[topic]
<span class="line-numbers"> <a href="#n7" name="n7">7</a></span>    section[
<span class="line-numbers"> <a href="#n8" name="n8">8</a></span>      @title[{{title}}]
<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>      @id[{{id}}]
<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span>      navigation[{{id}}]
<span class="line-numbers"><a href="#n11" name="n11">11</a></span>{{contents}}
<span class="line-numbers"><a href="#n12" name="n12">12</a></span>      navigation[{{id}}]
<span class="line-numbers"><a href="#n13" name="n13">13</a></span>    ]
<span class="line-numbers"><a href="#n14" name="n14">14</a></span>  ]
<span class="line-numbers"><a href="#n15" name="n15">15</a></span>]</pre>
		</div>
	</div>

	<p>Note that it takes the following attributes, passed automatically by Glyph when processing each topic:</p>
	<ul>
		<li><code>title</code> &#8212; the title of the topic.</li>
		<li><code>id</code> &#8212; the ID of the topic.</li>
		<li><code>contents</code> &#8212; the body of the topic.</li>
	</ul>

</section>
<section class="section">
	<header>
		<h3 id="index_layout" class="toc">Index Layout</h1>
	</header>
	<p>The default layout used to render the web index page (the layout used for the web5 index is very similar) is
		defined as follows:</p>
	<div class="CodeRay">
		<div class="code">
			<pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>document[
<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>  head[
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>    style[default.css]
<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>  ]
<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>  body[
<span class="line-numbers"> <a href="#n6" name="n6">6</a></span>    @class[topic]
<span class="line-numbers"> <a href="#n7" name="n7">7</a></span>    halftitlepage[
<span class="line-numbers"> <a href="#n8" name="n8">8</a></span>      title[]
<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>      subtitle[]
<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span>      author[]
<span class="line-numbers"><a href="#n11" name="n11">11</a></span>    ]
<span class="line-numbers"><a href="#n12" name="n12">12</a></span>    frontmatter[
<span class="line-numbers"><a href="#n13" name="n13">13</a></span>      toc[]
<span class="line-numbers"><a href="#n14" name="n14">14</a></span>    ]
<span class="line-numbers"><a href="#n15" name="n15">15</a></span>  ]
<span class="line-numbers"><a href="#n16" name="n16">16</a></span>]</pre>
		</div>
	</div>

	<p>Index layouts do not take any attribute or parameter (basically because they are used to produce only one page).
	</p>

</section>
<section class="section">
	<header>
		<h3 id="h_98" class="toc">Creating a Custom Layout</h1>
	</header>
	<p>To create a custom layout, proceed as follows:</p>
	<ul>
		<li>Create a <code>.glyph</code> file in the <code>lib/layouts</code> directory, within your project, e.g.
			<code>mytopic.glyph</code></li>
		<li>Add the layout code, making sure (for topic layouts) that all the attributes (<code>title</code>,
			<code>id</code>, <code>contents</code>) are specified correctly.</li>
		<li>Set the <code>output.*.layouts.topic</code> setting to the name of the new layout (<code>mytopic</code>).
		</li>
	</ul>
	<aside class="tip">
		<span class="note-title">Tip</span>You can override which layout to use on a specific topic by specifying it in
		a <code>@layout</code> attribute.

	</aside>

</section>

<nav class="navigation"><a href="/glyph/book/extending/interpreting.html">← Interpreting Glyph Code</a> | <a
		href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/further_reading.html">Further
		Reading →</a></nav>