How to add new templates in Kindle Clip

Apr 27, 2023 · [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.content}}
- {{note.date}}

#KindleNote

{{/if}}
{{/each}}

How to create a template

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.
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" }
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.
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!