Bloggo is a free and simplistic static site generator for individuals that prioritize content over features, it lets you use custom themes by running a simple command, and uses Go, Markdown and Frontmatter to generate HTML pages that are optimized for performance and SEO.
The following guide will give you a fresh copy of Bloggo, an understanding of its commands, and a live preview of the site that you will be further developing.
- Clone this repository
git clone https://github.com/kevinsuner/bloggo.git your-project-name
- Go to the cloned repository directory
cd /path/to/your-project-name
- Remove the
.git
folder from the cloned repository directoryrm -rf .git
- Run the
help
command to list all available Bloggo commands# For Linux users ./bin/bloggo-linux help # For Windows users ./bin/bloggo-windows.exe help # For MacOS users ./bin/bloggo-darwin help
- Run the
test
command to spin a live preview of the site athttp://127.0.0.1:5500/public
# For Linux users ./bin/bloggo--linux test # For Windows users ./bin/bloggo-windows.exe test # For MacOS users ./bin/bloggo-darwin test
The following configuration options can be set in the bloggo.yaml
file.
Name | Required | Example | Description |
---|---|---|---|
lang | true | lang: "en" |
The default language of the site |
base-url | true | base-url: "https://example.com" |
The base URL used in meta-tags and links |
theme | true | theme: "bloggo" |
The theme used across the site |
posts-limit | true | posts-limit: 10 |
The limit of articles shown in the index page |
pages | true | pages: ["index", "about", "archive", "404"] |
The pages that are going to be generated |
dirs | true | dirs: ["assets", "css"] |
The directories that are going to be copied from the theme folder to the public folder |
The following meta-tags can be used at the top of each .md
file like this:
---
title: "Markdown Syntax Guide | Bloggo"
raw-title: "Markdown Syntax Guide"
description: "This article offers a sample of basic Markdown syntax that can be used in Bloggo content files, also it shows whether basic HTML elements are decorated with CSS in a Bloggo theme."
keywords: "bloggo, go, golang, ssg, markdown, frontmatter, simple, minimalist"
author: "kevinsuner"
robots: "index, follow"
type: "article"
section: "posts"
published: "2023-09-27"
modified: "2023-09-27"
---
Name | Required | Usage | Description |
---|---|---|---|
title | true | title: "Home • Bloggo" |
The title of the page |
raw-title | only in posts | raw-title: "Home" |
The raw title of the page |
description | true | description: "The description" |
The description of the page |
keywords | true | keywords: "foo, bar, foobar" |
The keywords of the page |
author | true | author: "kevinsuner" |
The author of the page |
robots | true | robots: "index, follow" |
The instructions for the search engine |
type | true | type: "website" |
The type of the object for Open Graph |
section | only in posts | section: "posts" |
The section in which the article belongs |
published | only in posts | published: "2023-09-30" |
The date in which the article was published |
modified | only in posts | modified: "2023-09-30" |
The date in which the article was modified |
Given that Bloggo focuses on content over features, theming is very straightforward, as there is no possibility of generating more pages, unless you want to dig in the source code to do so. This is by design and I wish to keep it that way. Therefore to add a new theme, you only need to respect a certain file structure, this doesn't mean that you can't add new things, for example you've could create a navigation bar that included links to your social media, or a homepage with an avatar if you wish, so yes, you are certainly limited, but still you can do a lot of things within those bounds. If Bloggo doesn't suit your use-case there are wonderful alternatives like Hugo that will surely do.
As a recommendation, you can use the bloggo theme file structure as a reference.
bloggo/
assets/
css/
partials/
footer.html
header.html
nav.html
about.html
archive.html
index.html
post.html
At the moment the only proven way to deploy Bloggo is through Github Pages. This will surely change in the future as I try to deploy Bloggo in other services such as Netlify, Linode, etc...
Bloggo uses a custom GitHub Action located in action.yaml
to deploy to GitHub Pages, but, before you can start actually using it, you must tell your repo specifically to build your site that way. To do so you just have to:
- On Github, navigate to your site's repository
- Under your repository name, click Settings. If you cannot see the "Settings" tab, select the ••• dropdown menu, then click Settings
- In the "Code and Automation" section of the sidebar, click Pages
- Under "Build and Deployment", under "Source", select Github Actions
In case you want to build your own action, you're having some issues, or you just want to know more head to Configuring a publishing source for your GitHub Pages site or Using custom workflows with GitHub Pages.
All contributions are extremely appreciated, even though the capabilities of Bloggo are intended to be just a few, that doesn't mean that there is no room for improvement, because there is, so if you find places where things can be improved don't hesitate and open a pull request or an issue, as long as things are under Bloggo's scope I will be delighted to work on them, or allow other contributors to do so.
Aside from that, there are a couple of things that need to be respected in order to have something merged into Bloggo.
- Improvements over features
- Fit naturally into Bloggo's scope
The most important part is that each commit messages should have a title/subject in imperative mood starting with a capital letter and no trailing period: generator: Fix articles list being sorted in ascending order
NOT list sorted right.
. If you still unsure about how to write a good commit message this blog article is a good resource for learning that.
Most title/subjects should have a lower-cased prefix with a colon and one whitespace. The prefix can be:
- The name of the package where (most of) the changes are made (e.g.
parse: Add RawTitle to metadata struct
) - If the commit touches several packages with a common functional topic, use that as a prefix (e.g.
errors: Resolve correct line numbers
) - If the commit touches several packages without a common functional topic, prefix with
all:
(e.g.all: Reformat go code
) - If this is a documentation update, prefix with (e.g.
docs:
) - If nothing of the above applies, just leave the prefix out
Also, if your commit references some or more Github issues, always end your commit message body with See #1234 or Fixes #1234. Replace 1234 with the Github issue ID.
An example:
generator: Fix articles list being sorted in ascending order
Added a function that returns a sorted "map" by passing it an unsorted one,
it creates an "array" with the keys of the first "map", sorts the given "array"
using sort.StableSort and iterates over those keys to create new entries in the
new "map" and sets its value by accessing the first "map".
Fixes #1234
Bloggo uses the Go Modules support built into Go 1.11 to build. The easiest is to clone Bloggo in a directory outside of GOPATH
, as in the following example:
mkdir $HOME/src
cd $HOME/src
git clone https://github.com/kevinsuner/bloggo.git
cd bloggo
Now, to make a change to Bloggo's source:
- Create a new branch for your changes (the branch name is arbitrary):
git checkout -b abc123
- After making your changes, commit them to your new branch:
git commit -a -v
- Fork Bloggo in Github
- Add your fork as a new remote (the remote name, "foo" in this example, is arbitrary):
git remote add foo git@github.com:USERNAME/bloggo.git
- Push the changes to your new remote:
git push --set-upstream foo abc123
- You are now ready to submit a PR based upon the new branch in your forked repository
Prerequisites to build Bloggo from source:
- Go 1.19 or later
- GNU Make
- UPX (Ultimate Packer for eXecutables)
Bloggo makes use of a simple Makefile to cross-compile to Windows, Linux and macOS. Run the following command from the Bloggo working directory.
cd $HOME/src/bloggo
To build Bloggo:
make all
Bloggo makes use or has taken inspiration from a variety of open source projects including: