kevinsuner/bloggo

Bloggo is a free and simplistic static site generator for individuals that prioritize content over features.

Bloggo

🚀 Fast | 🪶 Lightweight | 📱 Responsive

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.

---

---

Usage

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.

1. Clone this repository

   git clone https://github.com/kevinsuner/bloggo.git your-project-name

2. Go to the cloned repository directory

   cd /path/to/your-project-name

3. Remove the .git folder from the cloned repository directory

   rm -rf .git

4. 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

5. Run the test command to spin a live preview of the site at http://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

Configuration

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

Frontmatter

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

Theming

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

Deploying

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...

Deploy with Github Pages

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:

1. On Github, navigate to your site's repository
2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the ••• dropdown menu, then click Settings
3. In the "Code and Automation" section of the sidebar, click Pages
4. 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.

Contributing

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

Git commit message guidelines

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

Fetching the source from Github

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:

1. Create a new branch for your changes (the branch name is arbitrary):

   git checkout -b abc123

2. After making your changes, commit them to your new branch:

   git commit -a -v

3. Fork Bloggo in Github
4. Add your fork as a new remote (the remote name, "foo" in this example, is arbitrary):

   git remote add foo [email protected]:USERNAME/bloggo.git

5. Push the changes to your new remote:

   git push --set-upstream foo abc123

6. You are now ready to submit a PR based upon the new branch in your forked repository

Building Bloggo with your changes

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

Credits

Bloggo makes use or has taken inspiration from a variety of open source projects including:

• github.com/yuin/goldmark
• github.com/yuin/goldmark-meta
• github.com/spf13/cobra
• github.com/spf13/viper
• github.com/gofiber/fiber/v2
• github.com/gohugoio/hugo
• github.com/egonelbre/gophers

bloggo's Issues

generator: Add support for the Github flavored Markdown spec

The markdown parser that Bloggo is using yuin/goldmark already supports this with its Built-in extensions so it should be pretty trivial to implement.

Add a makefile to build Go binaries and use UPX to compress them

Replace the current generator with a proper renderer

The way Bloggo is currently generating the index, about and archive pages under the hood is by having a specific receiver function per each one of them. Like this:

package main

import "fmt"

type Generator struct {
    BaseURL string
}

func (g *Generator) Index() {
    fmt.Println(g.BaseURL)
}

func (g *Generator) About() {
    fmt.Println(g.BaseURL)
}

func (g *Generator) Archive() {
    fmt.Println(g.BaseURL)
}

Although this solution works, from an extensibility and maintainability standpoint it wouldn't be wise to keep it as it is. In-order to tackle this problem the current generator must be replaced by a proper render package that accomplishes the aforementioned things.

The inner workings of the renderer are as straightforward as they can be, it profits from the user provided configuration and the metadata contained in the .md file to determine which options must be used when rendering.

flowchart LR
    1[config]-->2["render(...opts)"]
    3[markdown]-->4[frontmatter]-->2
    2-->5[html]

And it does not go against the KISS principle that Bloggo follows, because there will be a limit in the amount of options that users can provide in the configuration file. So, in the end index, about and archive will be the only pages that get rendered, but each one of them will be greatly customizable.

generator: Fix map not being properly sorted

At the moment the way the archive map is being created is by using the [year] part in the metadata.PublishedTime struct field as the key, and appending to it a post struct. This is happening inside a for-loop that iterates over a previously sorted []post array, so the inserts that are occurring on the archive map are being performed on a ordered way, but when printing out the map itself, the order appears to have been reversed and instead of it being [2018, 2017, 2016] is [2016, 2017, 2018]. This could be due to how maps are implemented in Go, or me not understanding them, so I'm thinking that it would be great to stop using a map and implement something along this lines Iterate over map.

Add deploy with Github Pages to the README.md

Add a section in the README.md that showcases how to create a Github Action to serve the static HTML generated by Bloggo on Github Pages

Copy all the directories contained in the selected theme excluding templates and partials

Currently the way directories from the theme folder are being copied is by using a function called copyDir and passing it the directory that needs to be copied. Instead a better idea would be to let the user define which directories from the theme folder must be copied.

themes/bloggo: Fix the delay when switching between dark/light mode and navigating to another page

At this moment, the way the Bloggo theme is switching between dark and light mode is by using a custom script located at the header, and using the window.onload event to trigger a function that determines which theme and theme-icon need to be set. Prior to this, the script was located in the footer template and worked just fine, but since now we are waiting for the whole page to load (including resources such as stylesheets, scripts, iframes, and images), the content gets displayed using the previous theme, and then after some milliseconds switches to the correct one.

Update the first paragraph in the README.md

Replace the first part of the paragraph "Bloggo is a simplistic" by "Bloggo is a free and simplistic"

Add update, generate and test commands

When creating the bloggo-demo repository, I noticed that the process of getting changes from upstream is not as ideal as I will wanted it to be, as I had to delete pretty much everything manually minus some specific files, and then re-generate the public folder.

To solve this problem I'm thinking of using Cobra to implement three separated commands:

• bloggo update Performs a git clone of Bloggo's master branch in a temporal folder, removes all folders minus user installed themes (bloggo theme comes by default, so it will get deleted too) and content.
• bloggo generate Generates the public directory and converts every Markdown file to HTML using go templates
• bloggo test Spins an HTTP server to serve the content contained in the public directory