<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 <ahref="/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>
<h3id="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>
<h3id="site-structure">Site Structure</h3>
<p>After you’ve cloned the <ahref="https://codeberg.org/tdarb/pblog">official pblog repo on Codeberg</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>
<p>This structure is completely customizable by simply editing the <code>pblog.sh</code> file (if you so desire).</p>
<h3id="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>
<h3id="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>
<spanid="cb2-2"><ahref="#cb2-2"aria-hidden="true"tabindex="-1"></a><spanclass="fu">title</span><spanclass="kw">:</span><spanclass="at"> Blog Title</span></span>
<p>This makes for an easier switch over from other SSG platforms like Jekyll or Hugo.</p>
<h3id="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>
<oltype="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 <ahref="/blog">on this very website</a>.</p>
<h3id="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 <ahref="https://app.netlify.com/drop">Netlify Drop</a> to make things as friction-less as possible.</p>
<h3id="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 <ahref="https://codeberg.org/tdarb/pblog">open a ticket or PR on the official repo</a>.</p>
<p>Thanks and happy blogging with <em>pblog</em>!</p>