How to add new templates in Kindle Clip

· [Daniel Baker]

I love when a product affords me the flexibility to do whatever I want with it. That’s why, in kindle-clip, I added the ability to customise the output format of the kindle clippings. With this new feature the app can output into what ever format you dream up. This level of customization means it’s possible to completely rewrite Amazons format into a format that suites your workflow.

By passing the name of the template in the command line params it’s possible to configure the output format of the highlights and notes. This is useful for writing highlights into a flexible format, or really nailing in a specific template just for your notes. In this post I’ll go over whats currently needed to create a new template.

Base Config

At the center of everything is a route config.json file. This file currently stores the file extension. In the future I will expand it to allow custom filename conventions as well as other tweaks to the files. But, for the time being, it was the most convenient way of configuring the desired file extension for the template.

  "format": "org"

File header

By default kindle clip pulls each book into it’s own file. If a file already exists for that book it will append to the file, not overwriting any modifications you’ve made to notes. One important thing to understand is if you remove a note from the file and it’s ID is also removed then the note or highlight will be re-imported and added to the end of the file. So you may find random highlights littering your new import if you removed any. To avoid this simply leave the ID for the note in the file, when removing the highlight. In the future I’ll provide a better way of skipping notes but for the time being this works.

When creating a new file we need to specify a file header. Do this by defining an header.hbs file. When writing a brand new book this template is rendered. Usually this is where you’ll put generic information related to the book such as the author, title, and the book id.

name type value nullable
author object the author of the book true
author.firstname string Authors firstname true
author.lastname string Authors surname true
title string the title of the book true
id string A guid id for the book false
id: {{bookId}}
title: {{title}}

Main content

The main content is generated using the content.hbs file. This is where you can specify how highlights are layed out along with their notes. Currently notes are attached to highlights as a property but I’m starting to rethink how this works, as it may not always be the case that a note should be a child of a highlight. In some cases you may want to link a note to the parent highlight but generate it as it’s own thing. With the current system that may be rather tricky as notes are not independent of a highlight and thus will always have the context of a highlight when they’re being written out.

For each highlight you have access to the following information.

name type value nullable
title string Title of the note false
content string The contents of the highlight false
page string The page number the highlight was made on true
location string The kindle location the highlight was made on true
date string The date the highlight was made true
note object The note associated with this highlight` true
note.content string The Content of the note false
note.date string The date the note was made false
note.id string A guid id representing the note string
id string A guid identifying the highlight string
{{#each this}}
# {{headline}}

> {{content}}
> - {{#if page}}Page {{page}},{{/if}}{{#if location}} Location {{location}},{{/if}} {{#if date}}Date {{date}}{{/if}}

- {{id}}

#Kindle #Quote

{{#if note}}
## Note

- {{note.date}}



How to create a template

  1. Create a new folder in the templates directory. Name it whatever you like, this is what you’ll be passiing as the command line parameter later.
  2. In the new folder create a file named config.json this is the config for the template. All we need right now is to add a extension property to the object. This should be the file extension you want to write to. In the case of markdown it would be md. You’ll end up with something like { extension: "md" }
  3. Create another file called header.hbs in this file add the heading for the file you want. This template will only be called once when anew file is created. See the section on file headers for a full list of available prooperties.
  4. Finally add a content.hbs file. This is called for every highlight and accompanying note. A full list of available properties is linked in the section above.

Wrapping up

That’s all there is to it. You can now call the application by running:

node index.js ~/path/to/my clippings.txt ~/path/to/output my-template

And your clipping file will bve parsed into the output format of your choice.

I’d love to hear from your experiences using kindle-clip, maybe you have feature requests or questions on usage, whatever they are feel free to reach out via twitter, or opening issues in the github repository. Happy clipping!