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.

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:https://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.

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

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:

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.

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:

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

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:

• 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