-
Notifications
You must be signed in to change notification settings - Fork 16
Expand file tree
/
Copy pathindex.xml
More file actions
386 lines (386 loc) · 17.2 KB
/
index.xml
File metadata and controls
386 lines (386 loc) · 17.2 KB
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
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
<!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://cdn.jsdelivr.net/npm/fork-awesome@1.2.0/css/fork-awesome.min.css"
integrity="sha256-XoaMnoYC5TH6/+ihMEnospgm0J1PM/nioxbOUdnM8HY=" crossorigin="anonymous" />
<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>
<a id="nav-npm" href="https://www.npmjs.com/package/sblg"><i class="fa fa-fw fa-nodejs"></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 id="explain-npm">NPM repository</span>
</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 merges articles into 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</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?
You write your HTML (really XHTML) articles and templates. <a href="sblg.1.html">sblg</a> pulls data from
the articles and merges it into the templates. This is usually orchestrated with a Makefile. And that's it.
<strong>You can write articles in any format — like Markdown — so long it converts into XHTML.</strong>
</p>
<p>
To get started, check if <span class="nm">sblg</span> is part of your system's package manager. If it's not,
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>, optionally
<code class="prettyprint lang-sh">make regress</code> and
<code class="prettyprint lang-sh">make valgrind</code> if <a href="https://valgrind.org/">valgrind</a> is
installed (you should also have <a href="https://jqlang.github.io/jq/">jq</a> installed),
then <code class="prettyprint lang-sh">make install</code>.
Systems with ancient <code>make</code> (like Mac OS X) will need to use <code>bmake</code> or update their
version of <code>make</code> to modern times.
</p>
<p>
<div data-sblg-nav="1" data-sblg-navsz="1" data-sblg-navtag="version" data-sblg-navstyle-element="discard"
data-sblg-navstyle-content="keep">
The current version is
<strong itemprop="softwareVersion">${sblg-titletext}</strong>, released on
<strong><time itemprop="dateModified" datetime="${sblg-datetime}">${sblg-date}</time></strong>.
</div>
<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="https://libexpat.github.io/">libexpat</a>.
It is a <a href="https://www.bsd.lv">BSD.lv</a> project and runs on OpenBSD, NetBSD, FreeBSD, Mac OS X, Linux,
Solaris, and IllumOS.
</p>
</section>
<section>
<h3 class="text">
latest version
</h3>
<div data-sblg-nav="1" data-sblg-navtag="version" data-sblg-navstyle-element="keep" data-sblg-navstyle-content="keep"
data-sblg-navsz="1" id="versions">
<div class="text">
<time datetime="${sblg-datetime}">${sblg-datetime-fmt}</time>:
version ${sblg-titletext}
</div>
<div class="text">
${sblg-aside}
</div>
</div>
<div class="text note">
<div>
<i class="fa fa-exclamation-circle"></i>
</div>
<div>
The latest versions above are produced in a <code class="prettyprint lang-html">data-sblg-nav="1"</code>
element limited to one article with the <code>version</code> navigation tag.
The <a href="archive.html">version history</a>, generated from
<a href="https://github.com/kristapsdz/sblg/blob/master/version.xml">version.xml</a> source,
has each version within an <code class="prettyprint lang-html"><article></code> with this tag, so
the newest appears as shown in the
<a href="https://github.com/kristapsdz/sblg/blob/master/index.xml">index.xml</a> source.
</div>
</div>
</section>
<section class="text">
<h3>
faq
</h3>
<ul>
<li data-sblg-nav="1" data-sblg-navtag="howto" data-sblg-navsort="cmdline" data-sblg-navstyle-content="keep"
data-sblg-navstyle-element="repeat-strip">
<a href="${sblg-base}.html">${sblg-title}</a>
</li>
</ul>
<div class="note">
<div>
<i class="fa fa-exclamation-circle"></i>
</div>
<div>
The FAQ consists of articles with the navigation tag <code>howto</code> formatted with
<a href="sblg.1.html">sblg</a> then passed into a
<code class="prettyprint lang-html">data-sblg-nav="1"</code> element in the
<a href="https://github.com/kristapsdz/sblg/blob/master/index.xml">index.xml</a> source.
The Markdown file is translated into XML in the
<a href="https://github.com/kristapsdz/sblg/blob/master/Makefile">Makefile</a>.
</div>
</div>
</section>
<section class="text">
<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 id="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>
<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>
<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>
output modes: 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</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</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 -o <a href="example1.html">example1.html</a> -t template.xml -c example.xml</pre>
</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>
output modes: 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 -o <a href="example2.html">example2.html</a> -t template.xml example1.xml example2.xml</pre>
</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>
output modes: 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 -o <a href="example3.html">example3.html</a> -t template.xml -C article1.xml article1.xml article2.xml</pre>
</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>
<h4>
output modes: json/atom mode
</h4>
<figure>
<img src="index4.svg" alt="JSON/Atom mode graph" />
</figure>
<p>
To export all articles into a JSON file or Atom feed, use their
<code><b>-j</b></code> or <code><b>-a</b></code> flags, respectively.
The JSON file is documented with a JSON schema distributed with the system.
A TypeScript definition of the exported type is also available on
<a href="https://www.npmjs.com">npm</a> as the
<a href="https://www.npmjs.com/package/sblg">sblg</a> package.
Use <code class="prettyprint lang-sh">npm i sblg --save-dev</code> to interface your TypeScript with a
<a href="sblg.1.html">sblg</a> blog.
</p>
</section>
<section class="text">
<h3>
contributing
</h3>
<p>
There are many ways to contribute to <span class="nm">sblg</span>, especially if you have a specific usage case
you'd like to see supported. The easiest is just to fork the repository on
<a href="https://github.com/kristapsdz/sblg">github</a>, add your feature, and make a pull request.
If you're looking for smaller ways to help, grep for
<code>TODO</code>, <code>FIXME</code>, or even <code>XXX</code> in the code for missing bits.
Lastly, the test coverage can certainly be improved by adding tests:
</p>
<div data-sblg-article="1" data-sblg-articletag="coverage"></div>
<p>
To improve these numbers, new tests may be written in the regression directory that exercise the file whose
coverage you'd like to increase. Please e-mail me or contact me on GitHub for details.
</p>
</section>
<footer>
©
<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>