forked from kristapsdz/sblg
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.xml
345 lines (345 loc) · 14.1 KB
/
index.xml
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
<!DOCTYPE html>
<html lang="en" prefix="og: http://ogp.me/ns#">
<head>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta charset="utf-8" />
<title>sblg: static blog utility</title>
<link rel="alternate" href="atom.xml" type="application/atom+xml" title="sblg version feed" />
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Alegreya+Sans:400,400italic,500" />
<link rel="stylesheet" href="https://bsd.lv/css/style.css" />
<link rel="stylesheet" href="index.css" />
<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script>
<meta property="og:title" content="sblg: static blog utility" />
<meta property="og:description"
content="A simple UNIX tool for creating static HTML pages from templates." />
<meta property="og:url" content="https://kristaps.bsd.lv/sblg/index.html" />
<meta property="og:type" content="website" />
<meta name="description"
content="A simple UNIX tool for creating static HTML pages from templates." />
</head>
<body itemscope="itemscope" itemtype="http://schema.org/SoftwareApplication">
<nav>
<div class="top text">
<a href="https://www.bsd.lv">BSD.lv</a>
<span itemprop="applicationCategory">tools for text processing</span>:
<a href="https://kristaps.bsd.lv/lowdown">lowdown</a>,
<a href="https://kristaps.bsd.lv/sblg">sblg</a>,
<a href="https://mandoc.bsd.lv">mandoc</a>
</div>
<div class="text">
<h1>
sblg <span>– static blog utility</span>
</h1>
</div>
<div class="nav text">
<a id="nav-gears" itemprop="downloadURL" href="snapshots/sblg.tar.gz"><i class="fa fa-fw fa-gears"></i></a>
<a id="nav-lock" href="snapshots/sblg.tar.gz.sha512"><i class="fa fa-fw fa-lock"></i></a>
<a id="nav-file" href="snapshots"><i class="fa fa-fw fa-file-o"></i></a>
<a id="nav-rss" href="atom.xml"><i class="fa fa-fw fa-rss"></i></a>
<a id="nav-github" href="https://github.com/kristapsdz/sblg"><i class="fa fa-fw fa-github"></i></a>
<span class="explain">
<span id="explain-gears">Download source</span>
<span id="explain-lock">Download checksum</span>
<span id="explain-file">Source archive</span>
<span id="explain-rss">Atom feed</span>
<span id="explain-github">GitHub repository</span>
</span>
<span id="nav-status">
<a href="https://kristaps.bsd.lv/cgi-bin/minci.cgi/index.html?project-name=sblg">
<i class="fa fa-tachometer fa-fw"></i>
Build Status
</a>
</span>
</div>
</nav>
<section class="text">
<p class="intro">
<span itemprop="name" class="nm">sblg</span> is
<span itemprop="description">a utility for creating static blogs</span>.
It knits together articles with templates to generate static HTML
files, Atom feeds, and JSON files.
It's built for use with
<a href="https://man.openbsd.org/make.1">make(1)</a>.
No PHP, no database: just a simple
<span itemprop="operatingSystem">UNIX</span> tool for pulling data
from articles and populating templates.
</p>
<p>
How does it work?
</p>
<p>
You write your HTML (really XHTML) articles and templates.
<a href="sblg.1.html">sblg(1)</a> pulls data from the articles and merges it into the templates.
This is usually orchestrated with a Makefile.
And that's it.
(You can write articles in any format—like Markdown—so
long as they can convert into a conforming XHTML document.)
</p>
<p>
To get started, download <a href="snapshots/sblg.tar.gz">sblg.tar.gz</a> (<a
href="snapshots/sblg.tar.gz.sha512">SHA512</a>), decompress, run <code class="prettyprint
lang-sh">./configure</code> then <code class="prettyprint lang-sh">make install</code>.
<nav data-sblg-nav="1" data-sblg-navxml="1" data-sblg-navsz="1" data-sblg-navtag="version">
The current version is <strong><span itemprop="softwareVersion">${sblg-titletext}</span></strong>,
released on
<strong><time itemprop="dateModified" datetime="${sblg-datetime}">${sblg-date}</time></strong>.
</nav>
Alternatively, use the <a href="https://github.com/kristapsdz/sblg">GitHub</a> repository or your operating
system's package manager (<a href="https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/www/sblg/">OpenBSD</a>,
<a href="https://github.com/kristapsdz/homebrew-repo">Homebrew</a>, etc.).
</p>
<p>
<span class="nm">sblg</span> is an <a href="http://opensource.org/licenses/ISC"
rel="license">open source</a> ISO C utility that depends only on <a
href="http://expat.sourceforge.net/">libexpat</a>.
It is a <a href="https://www.bsd.lv">BSD.lv</a> project.
</p>
<h3>
latest version
</h3>
</section>
<section id="versions">
<nav data-sblg-nav="1" data-sblg-navtag="version" data-sblg-navcontent="1" data-sblg-navsz="1" class="text">
<div>
<time datetime="${sblg-datetime}">${sblg-datetime-fmt}</time>:
version ${sblg-titletext}
</div>
<div>
${sblg-aside}
</div>
</nav>
</section>
<section class="text">
<div class="seeall">
(<a href="archive.html">See all versions</a>.)
</div>
<h3>
output modes
</h3>
<p>
There are three basic ways of populating templates:
<i>standalone</i> mode, which pastes a single article into a
template; <i>blog</i> mode, which pastes multiple
articles—like a blog front page; and <i>combined</i>,
which does both.
Blog mode can merge entire articles as well as just article snippets
and metadata for navigation and summary purposes.
(That's what this page does with its version notes.)
You can also do specialty modes of Atom and JSON feeds—also
part of this page.
</p>
<p>
The following templates illustrate <i>blog</i> and <i>combined</i>
and combined modes.
These are also used in the templates installed with the system, all
of which are responsive, have feeds, etc.
</p>
<div class="templates">
<figure>
<a href="examples/simple/index.html"><img src="template1.jpg" alt="" /></a>
<figcaption>
Simple <a href="examples/simple/index.html">page-per-article</a> template.
</figcaption>
</figure>
<figure>
<a href="examples/simple-frontpage/index.html"><img src="template2.jpg" alt="" /></a>
<figcaption>
Simple <a href="examples/simple-frontpage/index.html">front-page</a> template.
</figcaption>
</figure>
</div>
<div class="templates">
<figure>
<a href="examples/retro/index.html"><img src="template3.jpg" alt="" /></a>
<figcaption>
Retro <a href="examples/retro/index.html">front-page</a> style and Markdown.
</figcaption>
</figure>
<figure>
<a href="examples/brutalist/index.html"><img src="template4.jpg" alt="" /></a>
<figcaption>
<q>Brutalist</q>
<a href="examples/brutalist/index.html">front-page</a> style and Markdown.
</figcaption>
</figure>
</div>
<div class="templates">
<figure>
<a href="examples/photos-column/index.html"><img src="template5.jpg" alt="" /></a>
<figcaption>
Columnar
<a href="examples/photos-column/index.html">photo blog</a>
directly from EXIF data.
</figcaption>
</figure>
<figure>
<a href="examples/photos-grid/index.html"><img src="template6.jpg" alt="" /></a>
<figcaption>
Gridded
<a href="examples/photos-column/index.html">photo blog</a>
directly from EXIF data.
</figcaption>
</figure>
</div>
<h4>
standalone mode
</h4>
<figure>
<img src="index1.svg" alt="standalone mode graph" />
</figure>
<p>
Articles are just content within the <code class="prettyprint lang-html"><article
data-sblg-article="1"></code> tag of an HTML (or really XML) document.
<a href="sblg.1.html">sblg(1)</a> pulls articles and article metadata for populating navigation
elements and article elements in the templates.
Some important values, such as the document title, are extracted and may be filled in to the template.
You can also set custom variables, such as <q>foo</q> in the following example article.
</p>
<div class="prettyprint">
<pre class="prettyprint lang-html"><?xml version="1.0" encoding="utf-8"?>
<article data-sblg-article="1">
<header data-sblg-set-foo="bar">
<h1>Document Title</h1>
<address>Author Name</address>
<time datetime="2014-04-12">2014-04-12</time>
</header>
<aside>
This is pulled out for the page synopsis.
</aside>
<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua.
</p>
</article></pre>
</div>
<p>
You'll also need a template.
For standalone mode, this is just a regular HTML file where the <code class="prettyprint
lang-html"><article data-sblg-article="1"></code> tag is replaced by the page
contents.
</p>
<div class="prettyprint">
<pre class="prettyprint lang-html"><!DOCTYPE html>
<html lang="en">
<head>
<title>${sblg-titletext}</title>
<style>
body {width:100%; max-width: 50rem; margin: 0 auto;}
</style>
</head>
<body class="${sblg-get|foo}">
<article data-sblg-article="1"></article>
</body>
</html></pre>
</div>
<p>
There are all sorts of things documented in <a href="sblg.1.html">sblg(1)</a> that templates can fill in as
extracted from article text.
In the above example, a variable is used in the <code class="prettyprint lang-html"><title></code> element
and expands to the title in the source <code class="prettyprint lang-html"><h1></code> element.
</p>
<div class="prettyprint">
<pre class="prettyprint lang-sh">% sblg -t template.xml -c example.xml</pre>
</div>
<div class="button">
<a class="res" href="example1.html">view results <i class="fa fa-fw fa-chevron-right"></i></a>
</div>
<p>
This works well for putting simple documents into a template.
But what if we want to have these documents relate to each other, or have a single document relate to multiple
articles?
That's where blog mode comes into play.
</p>
<h4>
blog mode
</h4>
<figure>
<img src="index2.svg" alt="blog mode graph" />
</figure>
<p>
Blog mode is similar to standalone; however, you can also specify <code
class="prettyprint lang-html"><nav data-sblg-nav="1"></code> to fill in meta-data
from all articles passed into the command.
And unlike in standalone mode, you can't willy-nilly use <code class="prettyprint lang-sh">${sblg-title}</code>
variables in the global template scope, as it's not clear to which article they'd refer.
The <code class="prettyprint lang-html"><article></code> elements will be filled in with articles—as
many as you stipulate—there, as in the navigation, you can use the <code class="prettyprint
lang-sh">${sblg-title}</code> for the currently-printed article.
</p>
<div class="prettyprint">
<pre class="prettyprint lang-html"><!DOCTYPE html>
<html lang="en">
<head><title>My Blarg</title></head>
<body>
<nav data-sblg-nav="1"></nav>
<article data-sblg-article="1"></article>
<article data-sblg-article="1"></article>
</body>
</html></pre>
</div>
<p>
A Makefile makes this easy.
Simply let individual HTML articles be built with <code>-c</code>
from a template and source XML.
Then let the main blog page be built from all source XML and a
different template.
</p>
<div class="prettyprint">
<pre class="prettyprint lang-sh">% sblg -t template.xml example1.xml example2.xml</pre>
</div>
<div class="button">
<a class="res" href="example2.html">view results <i class="fa fa-fw fa-chevron-right"></i></a>
</div>
<p>
In most blogs, however, one wants both a main blogroll page and each
article to have navigation to other articles.
The latter is accomplished with <i>combined</i> mode, where
individual articles may also have navigation to all others.
</p>
<h4>
combined mode
</h4>
<figure>
<img class="larger" src="index3.svg" alt="combined mode graph" />
</figure>
<p>
A common usage is to mix up standalone and blog mode, where each article has its own page, and each page
refers to all other pages.
This can be effected using <i>combined</i> mode (<code><b>-C</b></code>), which specifies a single
article for display (like with standalone mode) but may reference multiple other articles in navigation.
</p>
<div class="prettyprint">
<pre class="prettyprint lang-html"><!DOCTYPE html>
<html lang="en">
<head><title>Blarg page: ${sblg-titletext}</title></head>
<body>
<nav data-sblg-nav="1"></nav>
<article data-sblg-article="1"></article>
</body>
</html></pre>
</div>
<p>
Combined mode works well with blog mode: combined for individual articles, blog for for landing page.
</p>
<div class="prettyprint">
<pre class="prettyprint lang-sh">% sblg -t template.xml -C article1.xml article1.xml article2.xml</pre>
</div>
<div class="button">
<a class="res" href="example3.html">view results <i class="fa fa-fw fa-chevron-right"></i></a>
</div>
<p>
For larger numbers of pages in combined mode, the cost of recompiling for each output can be quite high.
So there's also a mode (<code><b>-L</b></code>) for producing one output for each input, given all inputs.
These uses the default suffix mapping of replacing <code>.xml</code> with <code>.html</code> in the output.
</p>
</section>
<footer>
© 2013–2019,
<a itemprop="author" itemscope="itemscope" itemtype="http://schema.org/Person" rel="author" href="https://github.com/kristapsdz">
<span itemprop="name">Kristaps Dzonsons</span>
</a>
</footer>
</body>
</html>