/plugin-templates

Create templates in Joplin and use them to create new notes and todos.

Primary LanguageTypeScript

Templates Plugin
npm version

This plugin allows you to create templates in Joplin and use them to create new notes and to-dos.

Table of contents

Installing Plugin

  • Open Joplin
  • Go to Tools > Options > Plugins
  • Search for Templates
  • Click Install plugin
  • Restart Joplin to enable the plugin

Importing Legacy Templates

  • If you were already using the legacy version of templates, your templates will be automatically imported once you install the plugin. They will appear in an Imported Templates - dd/mm/yyyy notebook. See the README note in that notebook for more details.

  • Your existing templates will still be present in the templates directory but will be renamed from .md to .md.old. You can safely delete these old templates once you verify that they've been imported correctly in Joplin.

Using the Template Plugin

Adding a new template

Create templates by creating a new note or to-do in any notebook that:

  • Includes your template content
  • Is tagged with template

Using templates

You can access the templates options in Tools > Templates.

Features

Template variables

Built in variables

Built in variables are inserted automatically, without interaction from you. For example, in the following template, the date will be automatically added:

Date: {{date}}
Hours:
Details:

The currently supported built in template variables are:

Variable Description Example
{{date}} Today's date 2019-01-01
{{time}} Current time 13:00
{{datetime}} Current date and time 01/01/19 1:00 PM
{{#custom_datetime}} Current date and/or time formatted based on a supplied string (using moment.js formatting) {{#custom_datetime}}M d{{/custom_datetime}}
{{bowm}} Date of the beginning of the week (when week starts on Monday)
{{bows}} Date of the beginning of the week (when week starts on Sunday)

NOTE: All dates are formatted based on your Joplin settings in General > Date Format

Custom variables

You can also define custom variables in your template that prompt you to enter a value when you use the template. For example in the following example the name and color variables will prompt you each time you use the template:

---
name: text
color: dropdown(Red, Yellow, Green)

---

Hi there, {{ name }}. Your favorite color is {{ color }}. This note/to-do was created on {{ datetime }}.

The currently supported custom variable types are:

Type Example
text name: text
number count: number
boolean show_summary: boolean
date meeting_date: date
time meeting_time: time
dropdown color: dropdown(Red, Yellow)

Points to note

  • You can't use special characters ("@", ",", "#", "+", "(", etc.) or spaces in variable names. However, you can use "_" in variable names.
  • If you declare a custom variable with same name as the built-in variables, the custom variable value will be used.
  • Internally, Handlebars.Js is used to compile the templates. You can write templates to be compatible with Handlebars.

Advanced Usage

You can also define a label for each custom variable. Label is something that appears instead of the variable name in the variables input dialog. You can use the following syntax to do so.

---
name: text
project:
  label: Select a project
  type: dropdown(project 1, project 2, project 3)
show_summary:
  label: Add summary in note?
  type: boolean

---

Hi {{ name }},
This is a report for {{ project }}.

{{#if show_summary}}
## Summary
> Enter the summary here.
{{/if}}

Points to note

  • The indentation should be 2 spaces exactly. Don't use tabs for indentation otherwise it can result in errors.

Special variables

These are the variables that have a specific purpose other than being used in templates. Some of the important features of these special variables are

  • Both built-in and custom variables can be used while defining these variables.
  • The values of these variables can be used in the template body just like built-in and custom variables.

Currently there are two special variables.

Variable Purpose Example
template_title Title of the note/to-do created using this template. template_title: Standup - {{ date }}
template_tags Comma separated tags to be applied to the note/to-do created using this template. template_tags: spec, {{ project }}
template_notebook The ID of the target notebook for this template. Whenever a new note/to-do will be created by this template, it will be created in this target notebook. template_notebook: 82d2384b025f44588e4d3851a1237028

Points to note

  • If template_title is not provided, the title of the template will be used as a fallback value.
  • If a tag specified in template_tags doesn't exist already, it will be created.
  • You can't use these variable names i.e. template_title and template_tags for custom varaibles. In general, please avoid defining custom variables with template_ prefix.
  • To get the ID of a notebook, you can right click on that notebook and click on Copy notebook ID.

Example of a template using special variables

---
project: dropdown(project 1, project 2)
template_title: Weekly Meet - {{ project }} - {{ date }}
template_tags: meeting notes, {{ project }}

---

## {{ template_title }}

This note contains the meeting minutes of the weekly meet held on {{ datetime }} for {{ project }}.

Default Templates

You can define the templates you use the most as default templates. Currently you can have two default templates. One for notes and one for to-dos. You can also assign keyboard shortcuts to these defaults, so that you can quickly create a new note/to-do with the respective default template.

Changelog

See CHANGELOG.md.

Contributing

Contributions to this plugin are most welcome. Feel free to open a pull request or an issue. Make sure to use conventional commit messages if you're creating a pull request.