The service GitHub allows you to host a static website. The site can either be delivered as markdown (.md) documents or plain HTML. This blog generator creates plain HTML, meaning you can just upload the result to your GitHub reppository and your blog will be online.
First, you'll have to make a new GitHub repository.
The repository should be public and has to be named yourusername.github.io.
Here you simply replace yourusername with whatever your GitHub username
is. For me for example, it would be Bios-Marcel.github.io.
If you choose any name that differs from your account name, GitHub will instead
setup a sub page, using the same address. For example if you'd name your
repository blog, then the URL would be https://yourusername.github.io/blog.
Next, you'll need to setup the "blog writing environment" on your computer.
Open a terminal and execute the following:
cd ~/Documents/
mkdir blog-source
cd blog-sourceIf you want your blog files to reside somewhere else, simply change the
cd ~/Documents/ line to some other folder. The shortcut ~ is your
system users home directory.
Next, you need to copy the example directory into your newly
created blog-source directory as a. Rename the directory from example
to source.
Now, if you didn't name your repository as has been suggested earlier on, you'll have to edit your configuration to look like this:
{
"BasePath": "repository-name",
"SiteName":"Blog name",
"Author":"Your name",
"Description":"A blog about things",
"URL":"https://yourusername.github.io/",
"CreationDate":"2021-02-28T00:00:00+00:00",
"AddOptionalMetaData": true
}You'll have to replace the repository-name with whatever you named the
repository. While you are at it, you can also change the other settings to
whatever you desire.
For a full explanation of the config.json file, see The config.json
Lastly, you'll need to put the stasi-blog executable into that same folder.
So the structure of that folder should now look like this:
|--source
|--media
|--kaito-kid.png
|--pages
|--about.html
|--articles
|--kaito.html
|--config.json
|--favicon.ico
|--README.md
stasi-blog(.exe)
Next you build your blog, by running:
stasi-blog build -o "./" sourceAnd then serve a test version on your computer by running:
stasi-blog serve ./The tool will now show at the URL at which you can see the webpage in your browser.
TODO
TODO
Articles are currently written with plain HTML and require some meta
information. The metadata uses YAML and is separated from the page content by a
single line containing only ---. A document for an article should look like
this:
title:Clickbait Title
description: My thoughts on X.
date: 2020-12-10
tags: [categoryA,category]
---
<p>TEXT</p>
The sections tags and description are optional.
However, even though the content section is HTML, you don't need to write
a full web page. Instead, just write the text you'd normally want to see in
the content section of your article. While you usually start with a
heading, this can be omitted, as the heading is auto-generated by using the
title data.
Writing a custom page is similar to writing an article, the only difference
is, that you only require the sections title and content.
Meaning, that this would be enough already:
title: Custom Page Name
---
<p>TEXT</p>
Usually a table is divided into rows and columns, where each column has a
header and each row holds data. However, there are scenarios where you want
a table to have both a column header and a row header. You can do this using
the trh-table style class. An example would be:
<p>Opening times</p>
<table class="trh-table">
<!--Column headers-->
<tr>
<!--Left empty as this cell isn't meant to be used.-->
<th></th>
<th>Monday</th>
<th>Tuesday</th>
<th>Wednesday</th>
<th>Thursday</th>
<th>Friday</th>
</tr>
<!--Beginning of data-->
<tr>
<!-- Rowheader cell-->
<td>09:00 - 13:00</td>
<!-- Data cells-->
<td>Open</td>
<td>Open</td>
<td>Open</td>
<td>Open</td>
<td>Open</td>
</tr>
<tr>
<!-- Rowheader cell-->
<td>13:00 - 14:00</td>
<!-- Data cells-->
<td>Closed</td>
<td>Closed</td>
<td>Closed</td>
<td>Closed</td>
<td>Closed</td>
</tr>
<tr>
<!-- Rowheader cell-->
<td>14:00 - 18:00</td>
<!-- Data cells-->
<td>Open</td>
<td>Open</td>
<td>Open</td>
<td>Open</td>
<td>Closed</td>
</tr>
</table>For headings, you should use standard HTML tags h1 to h6. Note, that each
page, whether article or custom page, will automatically render the page title
as an h1 heading. Therefore all content headings should be h2 or smaller.
If you use headings in your HTML, they will automatically be augmented with an
anchor (a) to allow jumping directly to a heading.
Depending on what the usecase is, you should use the correct image format.
A good default choice is webp for images. It has very good lossless
compression and also offers lossy compression in scenarios where it isn't very
important to have maximum quality.
You should also avoid formats such as gif and instead use webm where
possible.
If you want to add images to your posts, try loading them lazily, as it allows your readers to get a readable page faster. Especially on mobile devices, old computers or devices with a slow internet connection, this can really help.
To lazily load an image, you need the loading="lazy" attribute.
One thing to keep in mind though, is that you need a default width and
height, as this will prevent layout shifting.
An example could look like this:
<img src="/images/postA/house.png" width="500" height="500" loading="lazy" alt="My new house"/>If you don't specify lazy as the loading strategy, but width and height
are presented, the image is automatically loaded lazily.
Each font, script, image, video, audio file or whatever you add to your page will cause higher load times and potentially data usage, which can potentially even cost your user more money.
By default all fonts are default fonts and no images are used, not even a favicon.