Caro
Caro is a Perl-based static blog generator backed by
smu
intended for text-only sites. Caro is
customisable, easy to extend, and fast. A blog with over 50 pages can be page
and built from scratch in under 2 seconds!
Key Features:
- Fast build times.
- Pre-configured with sensible defaults.
- Generates standards compliant HTML, CSS, and an RSS feed out of the box.
- No CPAN dependencies.
Why Does This Exist?
Caro tries to strike a middle-ground between being easily customisable and extensible without becoming overly complex or requiring dozens of external dependencies. Users are encourage to fork this repo and add their own features and tweaks as needed.
Installation
- Clone this repo.
- Install
smu
withmake install
. - Adjust the variables in each file in
scripts/
to your liking. - Start writing!
Writing a Blog Post
Caro supports most of the Markdown features you'd expect thanks to
smu
. To ensure the site builds as expected,
the first couple of lines in any blog post should be formatted as such (Dates
should be in RFC 3339 format):
# TITLE
**YYYY-MM-DD**
By default, Caro assumes your site is structured with blog posts grouped by year, like so:
HOME > blog > YEAR > FILE.markdown
I.e a given blog post could be found at:
https://example.com/blog/2020/file.html
Local Server
You can visit a local version of your site (on port 9001 by default) by running make serve
. Caro includes options for running a local server via:
- Python
- Ruby
- Quark
Project Contents
DIR | FILE | DESC. |
---|---|---|
src/ |
* | Site source code |
public/ |
* | Outputted HTML of source code (src/ ) |
scripts/ |
gen.pl |
Run markdown files in src/ through smu and export to public/
|
scripts/ |
bloglist.sh |
Generates and inserts blog post listings |
scripts/ |
rssmake.pl |
Generates and inserts RSS feed into public/
|
etc/ |
*.html |
Template files used for formatting |
etc/ |
favi/ |
Site favicons |
etc/ |
metadata/ |
OpenGraph information |
etc/ |
css/style.css |
CSS inlined during build |
etc/ |
robots.txt |
'robots' file |
etc/ |
rss/* |
RSS feed template files |
Makefile Contents
MAKE | DESC. |
---|---|
make |
Full build of site. Generates pages and RSS. |
pages |
Just build HTML portions of site. |
rss |
Just build RSS. Exports to public/rss.xml
|
clean |
Delete all *.html files from public/ . |
serve |
Start local server at localhost:9001
|
publish |
Do full build then push. |
stats |
Find out how many articles and words you've written. |
install |
Clones, compiles, and installs smu . |
Tooling
Caro is built with:
- Perl
- Karl Bartel's smu
- A few UNIX utilities, including:
date
sort
Web Standards Conformity
Generated sites should be fully web standards compliant. An example site can be tested below: