This document is meant to help you get a start with Clinklog 2, manage content, and import it from older versions if applicable. It assumes you know what Clinklog 2 is, what it's good for, and also how to use the command line.
This guide is written on a Linux machine. Things should work much the same on Mac and BSD; if you're on Windows, adjust as needed.
Quick start
Make sure you have Python 3.7 or newer installed, and that you've downloaded the scripts making up Clinklog to a suitable location. I just copy them to each project directory, seeing how they're all of 25K together.
felix@bigtom:~/Projects/test/web$ mkdir my-new-blog
felix@bigtom:~/Projects/test/web$ cd my-new-blog/
felix@bigtom:~/Projects/test/web/my-new-blog$ cp ~/bin/clinklog-* .
felix@bigtom:~/Projects/test/web/my-new-blog$ ./clinklog-init.py
Config placed in folder /home/felix/Projects/test/web/my-new-blog/content
Default theme placed in /home/felix/Projects/test/web/my-new-blog/theme
Your blog is ready.
felix@bigtom:~/Projects/test/web/my-new-blog$ ./clinklog-export.py
Loaded content/clinklog.ini
Theme loaded from: theme
Blog exported to: /home/felix/Projects/test/web/my-new-blog
felix@bigtom:~/Projects/test/web/my-new-blog$
By default, Clinklog assumes you're going to keep everything in one directory that you upload as such to the web server. Call the same scripts with a -h or --help argument to see other options, or just read on.
Managing content
To begin with, Clinklog creates one content file (called clinklog.ini), which looks like this:
[CONFIG]
title = My clinklog
desc = A collection of thoughts and bookmarks
link =
lang =
copy =
logo =
theme = theme
css = clinklog.css
[about]
title = About
desc = This is a note. It doesn't have a date. Maybe a link.
[1]
title = My first post
desc = Hello, world! Here I am. These are my thoughts.
pubdate = 2020-06-23 07:58
tags = news, meta
link =
At the very least you'll want to fill in the blog's link setting at the top, otherwise the newsfeed won't work right. The byline and/or license go in copy; logo should be the absolute URL of an image, if you have any. That's also due to the newsfeed.
On to the content, which mostly consists of items, like the one at the bottom. The part in square brackets is a slug: a bit of text to set the item apart. Examples of valid slugs include: "blah", "2", "blah2" or "2020-06-23". Slugs must be unique within each .ini file.
Items are always sorted by date, from newest to oldest. Because of that, they must always have one. Hours and minutes are optional, or you can add seconds, and even a timezone. Older versions translated everything to UTC, but Clinklog 2.1 only does that for the RSS feed. Elsewhere it sticks to local time unless otherwise instructed.
Without a date, an item becomes a note instead. Notes appear in a menu (at the top by default), and if they have a description, also on a page of their own. They are always sorted by slug.
Both items and notes can also have an explicit link that overrides their internal anchor. However only items get tags; they're ignored if given to a note.
Descriptions can extend over multiple lines, and contain HTML. Titles are optional.
Data import
Prior to release 2, Clinklog used to keep data in SQLite databases. To import from one of those into the new format, use the following command:
./clinklog-import.py -f clinklog.db > content/clinklog.ini
This of course assumes you just created the project directory and didn't add any new content since. Also, the import command uses the same defaults as Clinklog 1.x, so if your database is in the default location as above you can omit the -f argument.
For that matter, clinklog-export.py also saves the same files in the same locations by default, and recognizes the same options. Thus Clinklog 2 works as a drop-in replacement for older releases.
P.S. If you have custom CSS, copy it to the new theme folder before exporting the blog!