A blog-oriented static site generator
Project description
Bloggo
Bloggo is yet another blog-oriented static site generator.
Requirements
- Python 3.9+
- pip
Installation
- Run
python -m pip install bloggo
to install Bloggo - Get Bloggo's Boilerplate for your site's template and content
- When ready, generate site by running
bloggo
in your shell where the directoryresources
is
That's it, your static site should be available in the public
folder that was just created.
Every time you make changes, run bloggo
again to generate
new files. You can upload your public
folder's contents to any hosting provided you'd like.
Updating
To update Bloggo to the latest version simply run:
python -m pip install bloggo --upgrade
To find out what version of Bloggo you are currently running, open your shell and run:
bloggo --version
Content
Content files are very simple, YAML-esque (but one-level only!) structures. A complete example of a content file looks like this:
---
title: Hello, World
decription: A post about welcoming oneself to the world
date: 2021-02-12
---
Markdown content follows here.
- Dates have to be in a year-month-day format (you can format it later to whatever you want using the
format_date
helper) - Files have to be in a
.md
extension, such ashello-world.md
and placed inside theresources/content
directory. What's MD you say? It's Markdown. Beautiful, glorious, best friend of an efficient writer.
URLs
If you have a file called hello.md
in the root of the resources/content
directory, then that content
will be available via yoursite.com/hello. Likewise, if you put your stuff in a directory itself, like in a case of a blog post you would
have a file in resources/content/blog/hello.md
, then that content will be available via yoursite.com/blog/hello.
Note: the way Bloggo is written is that it always expects blog posts to live in the blog directory. I may at one point make it configurable (or you can make a pull request), but for now it is what it is.
Watch files for changes
In order to ease development of static sites with Bloggo, you can run it with a watcher via the
--watch
flag, which will then monitor the resources
directory for any changes and
upon detecting a change, generates a new static site.
Specify directories
By default, Bloggo expects resources to live in the resources
folder, and the
generated files will end up in a public
folder. If you don't like this however, you can
change it by passing a --resources-dir
and/or --out-dir
flags when calling Bloggo to change this.
Example:
bloggo --resources-dir ~/site/resources --out-dir ~/home/public_html
This would take the resources from the ~/site/resources
directory and it
would generate the static files into the ~/home/public_html
directory.
Templating
Bloggo uses Handlebars to put together your static site. It runs in a single templating file, called template.hbs
, in resources
directory.
I encourage you to make it your own, change things around and go crazy. But if you won't, that's okay, too.
Variables
Global variables:
is_home
returns true when being on the home page of the siteis_post
returns true when any content item is being viewed
Additionally, any configuration that you have added to the resources/config.json
file will be available as it's own
variable as well. For example a config such as:
{
"site_title": "Doggo's Bloggo"
}
would be usable in the template as {{site_title}}
.
Remember however that site_title
, site_url
and site_description
are all
required items so you must have them defined in config.json.
Contextual variables
Each of the posts yaml-esque key: value configuration is also available to you, in the post's context. Post context is available in two places:
When you are inside a is_post
context, you can simply access all the post's variables as-is. An example use-case would be:
{{#if is_post}}
<h2><a href="{{url}}">{{title}}</a></h2>
<div class="date">{{format_date date "%b %d, %Y"}}</div>
<div class="entry">{{entry}}</div>
{{/if}}
However, when you are inside a is_home
context, you c an access all the post's
variables from within a loop. An example use-case would be:
<ul>
{{#posts}}
<li>
<h2><a href="{{url}}">{{title}}</a></h2>
<div class="date">{{format_date date "%b %d, %Y"}}</div>
<div class="entry">{{entry}}</div>
</li>
{{/posts}}
</ul>
You see all the post's yaml-esque key: value things are available as {{key}}
, and the content of the post is available as {{{entry}}}
. Note
the three curly brackets, which Handlebars will render HTML with.
Helpers
format_date
helper
Allows you to format a given date
into any format you'd like, like this:
{{format_date date "%b %d, %Y"}}
Which would output something like February 14, 2021. For a full list of things you can pass it to format your date, refer to this documentation.
Assets
You should add your images, stylesheets, fonts and so on in the resources/assets
directory. This will get copied over
to the public
directory when generating, so your assets will be available via yoursite.com/assets/{...}
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for bloggo-1.2.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7bca11fa1fcf5ebf004a0477749063d8faeca98d015b67e96f39c49f39388acd |
|
MD5 | bc7f46e0049c201803cde6cbbacd034b |
|
BLAKE2b-256 | acb66c0922926c24d6c0b12237e2fde0e2aafb36cd42a81fbb1567e776742c77 |