README
¶
Bloggen
Bloggen is a static website generation tool that generates websites from plaintext files, with support for generating simple blogs.
Bloggen works by parsing text files containing metadata and text and generating HTML files from the passed information.
Bloggen has a simple template system, a simple macro system, and a simple metadata format.
Blogs are generated by reading a separate text file with a list of the blog entries in chronological order, and generating a listing of the titles of the blog entries.
Configuration
Configuration of the system is stored in a single, JSON encoded file.
Below is an example:
{
"site": {
"title": "My Cute Website",
"root": "https://mycutewebsite.com",
"footer": "My Cute Website is licensed under a CC BY-NC license.",
"lang": "en-ca",
"description": "A website which contains all of my thoughts!"
},
"blog": {
"recents_filename": "blog/index.html",
"archive_filename": "blog/archive.html",
"feed_filename": "blog/feed.xml",
"limit": 5
},
"system": {
"path": "/srv/sites/teaincodeout/http",
"templates": "/srv/sites/teaincodeout/data/template"
}
}
Site Configuration
The Site configuration block (residing under "site") contains variables that can be used throughout the site's templates.
For instance, the "title" variable is accessible in templates as ".Site.Title".
| Variable | Use | Default value |
|---|---|---|
| "title" | The title for the site. Used in the feed's title tag. | "" |
| "root" | The hostname for the site. Used to create permalinks. | "http://localhost" |
| "description" | The description for the site. Used in the feed's description tag. | "http/blog/feed.xml" |
| "author_name" | The default author to use in posts in the feed. | "unknown" |
| "footer" | A string to put in the footer of the site. | "" |
System Configuration
System configuration resides under the "system" block.
| Variable | Use | Default value |
|---|---|---|
| "path" | The path to the site's root directory. | "./http" |
| "templates" | The path to the site's templates. | "./data/templates" |
Blog Configuration
Blog configuration resides under the "blog" block.
| Variable | Use | Default value |
|---|---|---|
| "recents_filename" | The filename for the blog's recents page. | "http/blog/index.html" |
| "archive_filename" | The filename for the blog's archive page. | "http/blog/archive.html" |
| "feed_filename" | The filename where the atom feed should be rendered. | "http/blog/feed.xml" |
| "limit" | The number of blog posts to show on the recents page. | 5 |
Page Format
Every page on a Bloggen generated website is rendered from a .text file in
the site path.
For instance, to create readme.html, one would create readme.text with the
metadata required to render readme.html.
Metadata is always stored at the start of the file, above the actual content,
and the separation is indicated by a --- or a ===.
In this instance, a blog post might have the following metadata:
Title: New Post
Date: 2015-05-08 12:22
---
This indicates that the post will show up in the archives as being posted on May 8th, 2015 at 12:22.
The only required metadata for pages is "Title", and the only required metadata for blog posts are "Title" and "Date":
For instance:
Title: Projects
---
Template tags will determine what template to render around the content. More
on templates below.
Template Files
Page and Post Templates
The template system used by bloggen is based on the Go templates system. By default, all pages will be rendered with the template stored in "page.html" or "post.html" (for blog posts).
| Variable | Use |
|---|---|
| ".Site" | Contains values set in the "site" block in your configuration. |
| ".Page" | Contains variables specific to the current page. |
| ".Post" | Contains variables specific to the current post (equivalent to ".Page"). |
The simplest "page.html" template would be:
<html>
<head>
<title>{{.Site.Title}} - {{.Page.Title}}</title>
</head>
<body>
<h1>{{.Page.Title}}</h1>
{{.Page.Content | Markdown}}
</body>
</html>
The simplest "post.html" template would be:
<html>
<head>
<title>{{.Site.Title}} - {{.Post.Title}}</title>
</head>
<body>
<h1>{{.Post.Title}}</h1>
{{.Post.Content | Markdown}}
</body>
</html>
Note the use of .Post instead of .Page (this is for consistency with the
blog specific templates).
If so desired, you can replace a page's template using the Template variable
in the post's metadata. This advises bloggen to search for a template matching
the passed name instead of the default "page.html" or "post.html".
Recent Blog Posts
| Variable | Use |
|---|---|
| ".Site" | Contains values set in the "site" block in your configuration. |
| ".Posts" | Contains a list of Post variables. |
The Recent Blog Posts page (which uses the "recents.html" template) is very
similar to the "post.html" template, with the difference being that posts are
returned as a list. This means you have to loop through them, which you can do
with the range command.
An example "recents.html" could be:
<html>
<head>
<title>{{.Site.Title}} - Recent Posts</title>
</head>
<body>
<h1>Recent Posts</h1>
{{range .Posts}}
<h2>{{.Title}}</h2>
<p><a href="{{.Permalink}}">{{PrettyDate .Date}}</a></p>
{{.Content | Markdown}}
<hr>
{{end}}
<p><a href="{{.Site.Permalink "archive.html"}}">Archives</a></p>
</body>
</html>
Note: when using the range command, the current post is set to ., which
means that post variables are called directly.
Archive Page
| Variable | Use |
|---|---|
| ".Site" | Contains values set in the "site" block in your configuration. |
| ".Posts" | Contains a list of Post variables. |
The archive is very similar to the "Recents" page, but with the intention of only containing a listing of previous posts.
An example "archive.html" could be:
<html>
<head>
<title>{{.Site.Title}} - Recent Posts</title>
</head>
<body>
<h1>Archive</h1>
<ul>
{{ range .Posts }}
<li><a href="{{.Permalink}}">{{.Title}}</a></li>
{{end}}
</ul>
</body>
</html>
Note: when using the range command, the current post is set to ., which
means that post variables are called directly.
Publishing posts
Creating new posts is quite easy. Simply create an index.text file in a
directory in the site path, along with any content you want to post as well
(pictures, etc.)
Note: the name of the directory will be used to create the permalink for the post.
Like every page rendered by bloggen, blog posts will need to have metadata at
the start of the post describing the entry. For example:
Title: New Post
---
Once the post is ready to be published, you can do so by setting the publish date, using the "Date" variable:
Title: New Post
Date: 2021-01-01 12:00
---
Once the "Date" variable is added and set, that post will then be added to the archives page, the recents page (depending on the date it's published), and the feed.
To unpublish a page but leave it online, simply remove the "Date" variable and re-render the site.
Directories