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
|
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>Introducing pblog</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
/* The extra [class] is a hack that increases specificity enough to
override a similar rule in reveal.js */
ul.task-list[class]{list-style: none;}
ul.task-list li input[type="checkbox"] {
font-size: inherit;
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
/* CSS for syntax highlighting */
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { color: #008000; } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { color: #008000; font-weight: bold; } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>
<link rel="stylesheet" href="../style.css" />
</head>
<body>
<!-- Content placed here will appear directly after the opening <body> tag -->
<nav>
<a href="/">Home</a><span> / </span>
<a href="/blog">Blog</a><span> / </span>
<a href="/tweaks.html">Tweaks</a><span> / </span>
<a href="https://git.btxx.org/pblog">Download</a>
</nav>
<!-- Do not remove this opening article element -->
<article>
<header id="title-block-header">
<h1 class="title">Introducing pblog</h1>
<p class="date">Mon, 04 Jul 2022</p>
</header>
<nav id="TOC" role="doc-toc">
<ul>
<li><a href="#main-goal" id="toc-main-goal">Main Goal</a></li>
<li><a href="#site-structure" id="toc-site-structure">Site Structure</a></li>
<li><a href="#headers-and-footers" id="toc-headers-and-footers">Headers and Footers</a></li>
<li><a href="#posts-and-pages" id="toc-posts-and-pages">Posts and Pages</a></li>
<li><a href="#the-build-process" id="toc-the-build-process">The Build Process</a></li>
<li><a href="#uploading-to-the-www" id="toc-uploading-to-the-www">Uploading to the WWW</a></li>
<li><a href="#wrapping-up" id="toc-wrapping-up">Wrapping Up</a></li>
</ul>
</nav>
<p>This article is a <em>living document</em>. It will always have the most up-to-date information on getting started with <code>pblog</code>.</p>
<p><strong>Last Updated</strong>: July 27, 2022</p>
<hr />
<p>Although this project was already <a href="/blog/pblog-launch.html">announced</a> a couple days ago, I thought it might be best to actually breakdown <code>pblog</code> into greater detail.</p>
<p>Enough chit-chat, let’s get into it!</p>
<h3 id="main-goal">Main Goal</h3>
<p>The entire purpose of <code>pblog</code> is to be as bare-bones as possible, while still maintaining a pleasant writing workflow. Users write their posts and pages in Markdown - <em>pblog</em> handles everything else:</p>
<ul>
<li>Posts and pages generated via Pandoc with minimal CSS</li>
<li>RSS feed at <code>feed.xml</code></li>
<li>Generated blog listing at <code>blog/index.html</code></li>
<li>Browser-styled XML (in supported browsers)</li>
</ul>
<h3 id="site-structure">Site Structure</h3>
<p>After you’ve cloned the <a href="https://git.btxx.org/pblog">official pblog repo on sourcehut</a>, the next thing you should do is edit the main <code>_config.sh</code> file in the root directory. This will give you a better understanding of how everything is built.</p>
<p>Once generated, <em>pblog</em> structures the final website files as such:</p>
<pre class="shell"><code>_output/
|__blog/
|__index.html
|__blog-post-example.html
|__media/
|__feed.xml
|__index.html
|__rss.xsl
|__style.css</code></pre>
<p>This structure is completely customizable by simply editing the <code>_config.sh</code> file (if you so desire).</p>
<h3 id="headers-and-footers">Headers and Footers</h3>
<p>By default <code>pblog</code> will add the header and footer includes to every individual post and page. To edit these, simply open the <code>_header.html</code> and <code>_footer.html</code> files respectively.</p>
<p><strong>Important</strong>: To avoid rendering issues DO NOT remove the included <code>article</code> opening and closing tags within those files. Everything else you can edit, remove, etc.</p>
<h3 id="posts-and-pages">Posts and Pages</h3>
<p>Posts and pages are written via Markdown inside the <code>posts</code> and <code>pages</code> folders respectively.</p>
<p>Individual posts require the following headers (take note of the date format):</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="pp">---</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="fu">title</span><span class="kw">:</span><span class="at"> Blog Title</span></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="fu">date</span><span class="kw">:</span><span class="at"> Mon, 04 Jul 2022</span></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="pp">---</span></span></code></pre></div>
<p>while individual pages only require a <code>title</code>:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="pp">---</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="fu">title</span><span class="kw">:</span><span class="at"> Page Title</span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a><span class="pp">---</span></span></code></pre></div>
<p>This makes for an easier switch over from other SSG platforms like Jekyll or Hugo.</p>
<h3 id="the-build-process">The Build Process</h3>
<p>The main variables at the top of the <code>pblog.sh</code> file need to edited with your own details before generating your website. Those variables are fairly self-explanatory and simple to edit.</p>
<p>All you need to do now is run <code>make</code> (or <code>make serve</code> if you’re looking to test locally) and you’re done. Your website should now be fully generated inside the include <code>_output</code> directory. For quick reference:</p>
<ol type="1">
<li><em>pblog</em> converts your Markdown posts into two variations of HTML
<ul>
<li>One is used specifically for rendering itself inside the RSS feed</li>
<li>The other is used for linking in a browser</li>
</ul></li>
<li>Next, <em>pblog</em> converts your Markdown pages into HTML</li>
<li>All of these generated HTML files are then moved to the <code>_output</code> folder</li>
</ol>
<p><em>pblog</em> is also smart enough to automatically generate a main blog list directory for you. This <code>index.html</code> file is placed inside the <code>_output/blog</code> folder on build. You can see an example of the blog list <a href="/blog">on this very website</a>.</p>
<h3 id="uploading-to-the-www">Uploading to the WWW</h3>
<p>Those with more experience will probably lean towards using a utility like <code>rsync</code> to sync the contents of their <code>_output</code> folder with their web server. For those with less experience, I recommend using something like <a href="https://app.netlify.com/drop">Netlify Drop</a> to make things as friction-less as possible.</p>
<h3 id="wrapping-up">Wrapping Up</h3>
<p>There isn’t much else to say. <code>pblog</code> is as static or flexible as you chose it to be. If you have any ideas on how to improve things or come across any bugs, please <a href="https://git.sr.ht/~bt/pblog">open a ticket or PR on the official repo</a>.</p>
<p>Thanks and happy blogging with <em>pblog</em>!</p>
</article><!-- Do not remove this closing article element -->
<!-- Content placed here will appear directly before the closing </body> tag -->
<footer>
<br>
<hr>
<p><small>Powered by <a href="https://pblog.btxx.org">pblog</a><br>
Made with ♥ for a simpler web.</small></p>
</footer>
</body>
</html>
|
