The blog code powering my blog.
See API.md on how to use this.
Compatible with babashka and Clojure.
Includes hot-reload. See it in action here.
Copy the config from bb.edn
in this project to your local bb.edn
. Then run bb tasks
:
$ bb tasks
The following tasks are available:
new Create new blog article
delete Delete blog article
quickblog Render blog
watch Watch posts and templates and render file changes
publish Publish blog
clean Remove cache and output directories
migrate Migrate away from `posts.edn` to metadata in post files
To create a new blog post:
$ bb new :file "test.md" :title "Test"
To watch:
$ bb watch
Quickblog can be used in Clojure with the exact same API as the bb tasks.
Default options can be configured in :exec-args
.
:quickblog {:deps {io.github.borkdude/quickblog
{:git/sha "b69c11f4292702f78a8ac0a9f32379603bebf2af"}
org.babashka/cli {:mvn/version "0.3.31"}}
:main-opts ["-m" "babashka.cli.exec" "quickblog.api"]
:exec-args {:blog-title "REPL adventures"
:out-dir "public"
:blog-root "https://blog.michielborkent.nl/"}}
After configuring this, you can call:
clj -M:quickblog new :file "test.md" :title "Test"
To watch:
clj -M:quickblog watch
etc.
NOTE: when enabling or disabling a favicon, you must do a full re-render of
your site by running bb clean
and then your bb render
command.
To enable a favicon, add :favicon true
to your quickblog opts (or use --favicon true
on the command line).
quickblog will render the contents of templates/favicon.html
and insert them
in the head of your pages.
You will also need to create the favicon assets themselves. The easiest way is
to use a favicon generator such as
RealFaviconGenerator, which will let you
upload an image and then gives you a ZIP file containing all of the assets,
which you should unzip into your :assets-dir
(which defaults to assets
).
You can read an example of how to prepare a favicon here: https://jmglov.net/blog/2022-07-05-hacking-blog-favicon.html
quickblog's default template expects the favicon files to be named as follows:
android-chrome-192x192.png
android-chrome-512x512.png
apple-touch-icon.png
browserconfig.xml
favicon-16x16.png
favicon-32x32.png
favicon.ico
mstile-150x150.png
safari-pinned-tab.svg
site.webmanifest
If any of these files are not present in your :assets-dir
, a quickblog default
will be copied there from resources/quickblog/assets
.
Social media sites such as Facebook, Twitter, LinkedIn, etc. display neat little
preview cards when you share a link. These cards are populated from certain
<meta>
tags (as described in "How to add a social media share card to any
website",
by Michelle Mannering) and typically contain a title, description / summary, and
preview image.
By default, quickblog adds tags for the page title for all pages and descriptions for the following pages:
- Index:
{{blog-description}}
- Archive: Archive -
{{blog-description}}
- Tags: Tags -
{{blog-description}}
- Tag pages: Posts tagged "
{{tag}}
" -{{blog-description}}
If you specify a :blog-image URL
option, a preview image will be added to the
index, archive, tags, and tag pages. The URL should point to an image; for best
results, the image should be 1200x630 and maximum 5MB in size. It may either be
an absolute URL or a URL relative to :blog-root
.
For post pages, meta tags will be populated from Description
, Image
,
Image-Alt
, and Twitter-Handle
metadata in the document.
If not specified, Twitter-Handle
defaults to the :twitter-handle
option to
quickblog. The idea is that the :twitter-handle
option is the Twitter handle
of the person owning the blog, who is likely also the author of most posts on
the blog. If there's a guest post, however, the guest blogger can add their
Twitter handle instead.
For example, a post could look like this:
Title: Sharing is caring
Date: 2022-08-16
Tags: demo
Image: assets/2022-08-16-sharing-preview.png
Image-Alt: A leather-bound notebook lies open on a writing desk
Twitter-Handle: quickblog
Description: quickblog now creates nifty social media sharing cards / previews. Read all about how this works and how you can maximise engagement with your posts!
You may have already heard the good news: quickblog is more social than ever!
...
The value of the Image
field is either an absolute URL or a URL relative to
:blog-root
. As noted above, images should be 1200x630 and maximum 5MB in size
for best results.
Image-Alt
provides alt text for the preview image, which is extremely
important for making pages accessible to people using screen readers. I highly
recommend reading resources like "Write good Alt Text to describe
images" to
learn more.
Resources for understanding and testing social sharing:
quickblog uses the following templates in site generation:
base.html
- All pages. Page body is provided by the{{body}}
variable.post.html
- Post bodies.style.css
- Styles for all pages.favicon.html
- If:favicon true
, used to include favicon in the<head>
of all pages.
quickblog looks for these templates in your :templates-dir
, and if it doesn't
find them, will copy a default template into that directory. It is recommended
to keep :templates-dir
under revision control so that you can modify the
templates to suit your needs and preferences.
The default templates are occasionally modified to support new features. When
this happens, you won't be able to use the new feature without making the same
modifications to your local templates. The easiest way to do this is to copy the
refresh-templates
task from quickblog's bb.edn
into your own bb.edn
and
run bb refresh-templates
.
quickblog now keeps metadata for each blog post in the post file itself. It used
to use a posts.edn
file for this purpose. If you are upgrading from a version
that used posts.edn
, you should run bb migrate
and then remove the
posts.edn
file.
Feel free to send PRs for improvements.
My wishlist:
- There might be a few things hardcoded that still need to be made configurable.
- Upstream improvements to markdown-clj