Twitter AvatarJökull Sólberg Auðunsson

December 11, 2011

Calepin Guide

Custom Domains

On 17 January 2012 custom domains were introduced. Create a CNAME record that points at calepin.co and update the Calepin settings in Step 2 of the calepin.co interface. The CNAME field there should be the domain you are using. Calepin will redirect the username.calepin.co to the custom domain. You can also create an A record and point to the calepin.co IP address, but it is less reliable.

Please note that new CNAMES are syncronized on the Calepin web server configuration every hour, so give it a moment after you configure it.

Metadata

All Calepin posts require the top section of each post to include metadata. The required values are Title and Date. If these two are not provided the post will be ignored.

Title: The Hitchhiker's Guide To Publishing
Date: 2011-12-12

For travellers without stationery ...

Leave a linebreak between the metadata and the first paragraph or header.

Date formats

The following date formats are recognized by Calepin

  • 13.12.2011
  • 2011/12/13
  • 2011-12-13
  • 2011-12-13 12:30
  • 2011-12-13 12:30:10

Possible Metadata

  • Slug: A URL safe string to use for the base of the article URL, otherwise generated from the title. If you have a long title you might want to make a nicer URL with this metadata.
  • Tags & Category: See the "Tags & Categories" section below.
  • Author: This is only displayed in the Atom feed. Overwrites the author value of settings.json.
  • Status: If this value is set to draft the post will not be rendered in the output.

Code Highlighting

Calepin supports code highlighting of code blocks. A code block is indented with four spaces. To highlight the source make the first line :::python - replacing "python" with a syntax supported by the Pygments library.

Abstract

If you would like to attach an abstract to the post links on the index page include Abstract: Lorem ipsum ... in the post metadata.

Ordering Posts

The index page orders posts by date and time. If you have two posts on the same day, go with a format that includes the time too (for both posts).

2011-10-15 12:10

Managing Your Markdown Files

The filenames are more or less ignored by Calepin so you are free to use them for your own organization. Here is a directory listing that might give you some ideas for how you can organize your Calepin folder.

% ls -1 ~/Dropbox/Apps/Calepin/
2010-curry-recipe.md
2010-reader-tutorial.md
2011-ad-channel.md
2011-ipad-2-review.md
2011-value-of-openness.md
draft-framework-evolution.md
draft-standing-desk-experience.md

Tags & Categories

If you feel the need to file your writing into categories you can do so with Tags and Categories in the metadata section.

Title: I Love Tags
Date: 2011-01-20
Tags: filing, organization
Category: ocd

Adding a Photo to Posts

Step 1: Copy or move the photo file into your Dropbox public folder. Right click the file and copy the public URL from the Dropbox menu.

Step 2: In your text editor place the image with this markdown, replacing the image source URL with the one in your clipboard:

![Teapot](http://dl.dropbox.com/u/153068/12036372529.gif)

Controlling the Post URL

Calepin is all about giving your writing a universally accessible web address. Normally the URL for a post is derived from the Title and converted to an internet friendly string. The title "My First Blog Post" becomes my-first-blog-post. Calepin then appends .html so the result is something like this:

http://jokull.calepin.co/my-first-blog-post.html

You can define your own URL title to overwrite this behavior, for instance if the title is very long and you want a shorter URL. Just add a Slug: field to the metadata section.

Title: My First Blog Post
Date: 2011-12-12
Slug: first-post

RSS/Atom Feeds

If you think Calepins don't support an XML feed of all the latest writing you're WRONG. Your fans can get all the latest writing delivered to their feed readers by pasting the base URL (http://username.calepin.co). The Atom feed is automatically picked up.

settings.json

For the adventurous Calepin allows further tweaking. The following values, if found as values of a JSON object in a settings.json alongside your posts, can modify the output blog in various ways.

  • author - Overwrites the author value of the default in the Atom feed author.
  • default_date_format - A Python strftime string to modify the way dates are displayed.
  • google_analytics - Will render the tracking code for this Google Analytics ID on every page.
  • default_pagination - The number of items per page. Default is false which disables pagination.
  • with_future_dates - Whether Calepin should display articles with a future date or not. Default is false.
  • clean_urls - If set to true, Calepin will create a directory for every post and output to index.html. Most webservers can then display cleaner looking URL's without the .html file extension in the article URL.
  • output_source - This outputs the source for all articles on the .txt URL. If the article url is article.html, article.txt would display the source file in plaintext. Default: true.

Sample settings.json:

{
  "author": "Jökull Sólberg",
  "default_date_format": "%B %e, %Y",
  "with_future_dates": false,
  "google_analytics": "UA-12230384-12"
}
By Jökull Sólberg Auðunsson