TP-NOTE(1) Version 1.23.3 | Tp-Note documentation

In case the clipboard is empty while starting, the new note is created with the templates: “tmpl.from_dir_content” and “tmpl.from_dir_filename”. By default, the new note’s title is the parent’s directory name. The newly created file is then opened with an external text editor, allowing it to change the proposed title and add other content. When the text editor closes, Tp-Note synchronizes the note’s metadata and its filename. This operation is performed with the “tmpl.sync_filename” template.

Example: the clipboard is empty and “<path>” is a directory (or empty):

tpnote "./03-Favorite Readings/"

or

cd "./03-Favorite Readings"
tpnote

creates the document:

./03-Favorite Readings/20211031-Favorite Readings--Note.md

with the content:

---
title:      Favorite Readings
subtitle:   Note
author:     Getreu
date:       2021-10-31
lang:       en-GB
---

When “<path>” is a directory and the clipboard is not empty, the clipboard’s content is stored in the variable “{{ clipboard }}”. In addition, if the content contains an hyperlink in Markdown format, the hyperlink’s name can be accessed with “{{ clipboard | link_text }}”, its URL with “{{ clipboard | link_dest }}” and its title with “{{ clipboard | link_title }}”. The new note is then created with the “tmpl.from_clipboard_content” and the “tmpl.from_clipboard_filename” templates. Finally, the newly created note file is opened again with some external text editor. When the user closes the text editor, Tp-Note synchronizes the note’s metadata and its filename with the template “tmpl.sync_filename”.

Note: this operation mode also empties the clipboard (configurable feature).

Clipboard simulation

When no mouse and clipboard is available, the clipboard feature can be simulated by feeding the clipboard data into stdin:

echo "[The Rust Book](<https://doc.rust-lang.org/book/>)" | tpnote

Tp-Note behaves here as if the clipboard contained the string: “[The Rust Book](<https://doc.rust-lang.org/book/>)”.

tpnote "./03-Favorite Readings/"

cd "./03-Favorite Readings/"
tpnote

./03-Favorite Readings/20211031-Who Moved My Cheese--Note.md

---
title:      Who Moved My Cheese
subtitle:   Note
author:     Getreu
date:       2021-10-31
lang:       en-GB
---

Who Moved My Cheese?

Chapter 2

tpnote './doc/Lecture 1'

./doc/Lecture 1/20211031-The Rust Book--Notes.md

---
title:      The Rust Book
subtitle:   URL
author:     Getreu
date:       2021-10-31
lang:       en-GB
---

I recommend:
[The Rust Book](<https://doc.rust-lang.org/book/>)

tpnote

---
title:      Todo
subtitle:   Note
author:     Getreu
date:       2023-09-15
lang:       fr-FR

file_ext:   mdtxt
---

nothing

echo -e "---\ntitle: Todo\nfile_ext: mdtxt\n---\n\nnothing" | tpnote

curl 'https://blog.getreu.net' \
| pandoc --standalone -f html -t markdown_strict+yaml_metadata_block \
| tpnote

---
title:      Jens Getreu's blog
subtitle:   Note
author:     Getreu
date:       2023-09-15
lang:       en

viewport:   width=device-width, initial-scale=1.0, maximum-scale=1
---

<a href="/" class="logo">Jens Getreu's blog</a>

-   [Home](https://blog.getreu.net)
-   [Categories](https://blog.getreu.net/categories)

When “<path>” points to an existing file, whose file extension is other than “.md”, a new note is created with a similar filename and a reference to the original file is copied into the new note’s body. If the clipboard contains some text, it is appended there also. The logic of this is implemented in the templates: “tmpl.annotate_file_content” and “tmpl.annotate_file_filename”. Once the file is created, it is opened with an external text editor. After editing the file, it will be - if necessary - renamed to be in sync with the note’s metadata.

Example:

:> "Classic Shell Scripting.pdf"

tpnote "Classic Shell Scripting.pdf"

creates the note:

Classic Shell Scripting.pdf--Note.md"

with the content:

---
title:      Classic Shell Scripting.pdf
subtitle:   Note
author:     Getreu
date:       2023-09-15
lang:       en-US
---

[Classic Shell Scripting.pdf](<Classic Shell Scripting.pdf>)

The configuration file variable “filename.extensions” list all the file extensions that Tp-Note recognizes as own file types. Only foreign file types can be annotated.

Note that the file annotation mode also reads the clipboard’s content: when it is not empty, its data is appended to the new note’s body.

Consider the content of the following text file “Ascii-Hangman--A game for children.md” whose creation date is 13 March 2022:

A little game designed for primary kids to revise vocabulary in classroom.

To convert the text file into a Tp-Note file type:

tpnote --add-header --batch "Ascii-Hangman--A game for children.md"

NB: the “--add-header” flag is actually not necessary, as it is enabled by default through the configuration file variable “arg_default.add_header = true”.

As a result of the above command, Tp-Note converts the filename into:

20220313-Ascii-Hangman--A game for children.md

and prepends a YAML header to the file’s content:

---
title:      Ascii-Hangman
subtitle:   A game for children
author:     Getreu
date:       2022-03-13
lang:       en-US

orig_name:  Ascii-Hangman--A game for children.md
---

A little game designed for primary kids to revise vocabulary in classroom.

Unless invoked with “--batch” or “--view”, Tp-Note launches an external text editor after creating a new note. This also happens when “<path>” points to an existing “.md”-file.

Example: edit the note from the previous example:

cd "./03-Favorite Readings"
tpnote 20211031-Favorite Readings--Note.md

Before launching the text editor and after closing it, Tp-Note synchronizes the filename with the note’s metadata. When the user changes the metadata of a note, Tp-Note will replicate that change in the note’s filename. As a result, all your note’s filenames always correspond to their metadata, which helps to retrieve your notes in large data pools.

Example:

tpnote "20200306-Favorite Readings--Note.md"

The way how Tp-Note synchronizes the note’s metadata and filename is defined in the template “tmpl.sync_filename”.

Once Tp-Note opens the file in your text editor, let’s assume you decide to change the title in the note’s YAML metadata section from “title: Favorite Readings” to “title: Introduction to bookkeeping”. After closing the text editor, Tp-Note updates the filename automatically:

20200306-Introduction to bookkeeping--Note.md

Note: the sort tag “20200306” has not changed. The filename synchronization mechanism by default never does. (See below for more details about filename synchronization).

Tp-Note is designed to be compatible with “Pandoc’s and”RMarkdowns document structure as shown in the figure below. In this documentation the terms “YAML header”, “header” and “front matter” are used as synonyms to designate to document’s metadata block at the beginning of the text file:

---
<YAML-front-matter>
---

<document-body>

The YAML front-matter starts at the beginning of the document with “---” and ends with “...” or “---”. Note that according to the YAML standard, string literals are always encoded as JSON strings. By convention, a valid Tp-Note file has at least one YAML field named “title:” (the name of this compulsory field is defined by the “tmpl.compulsory_header_field” variable in the configuration file and can be changed there).

Note that prepended text, placed before the YAML front-matter, is ignored. There are however certain restrictions: If present, the skipped text should not be too long (cf. constant “BEFORE_HEADER_MAX_IGNORED_CHARS” in the source code of Tp-Note) and it must be followed by at least one blank line:

Prepended text is ignored.

---
<YAML-front-matter>
---

<document-body>

There is no restriction about the markup language being used in the note’s text body. However, the default templates assume Markdown and the file extension “.md”. Both can be changed easily by adapting Tp-Note’s configuration file. Besides the requirements concerning its header, a valid Tp-Note file must have a filename extension that is listed in one of the configuration file variables: “filename.extension_*”. The latter also determine which internal markup language render is called for Tp-Note’s internal viewer.

There are two ways to modify the default file editor, Tp-Note launches when it starts: either you can modify the configuration file variables “app_args.*.editor” and “app_args.*.editor_console”, or alternatively, you can set the “TPNOTE_EDITOR” environment variable (cf. examples in the chapter ENVIRONMENT_VARIABLES below).

The configuration file variables “app_args.unix.editor” and “app_args.unix.editor_console” define lists of external text editors to be launched for editing. The lists contain by default well-known text editor names and their command line arguments for Unix like operating systems. For other systems consult: “app_args.windows.editor”, “app_args.windows.editor_console”, “app_args.macos.editor” and “app_args.macos.editor_console”. Tp-Note tries to launch every text editor in “app_args.*.editor” from the beginning of the list until it finds an installed text editor. When Tp-Note is started on a Linux console, the list “app_args.*.editor_console” is used instead. Here you can register text editors that do not require a graphical environment, e.g. “vim” or “nano”. In order to use your own text editor, just place it at the top of the list. To debug your changes invoke Tp-Note with “tpnote --debug debug --popup --edit”.

The following example showcases the configuration for the Kate file editor. The entry “kate” launches the binary, while the command line parameter “--block” guarantees, that the launched process blocks until the user closes the editor. Tp-Note detects the end of the process, checks if the title of the note files has changed in its YAML header and renames the note file if necessary.

[app_args]
unix.editor = [
  [
    'kate',
    '--block'
  ]
]

The equivalent configuration with environment variable:

TPNOTE_EDITOR="kate --block" tpnote

All items in the above list are subject to limited template expansion allowing to insert the value of environment variables. Consider the following example:

[app_args]
windows.editor = [
    [
    '{{ get_env(name="LOCALAPPDATA") }}\Programs\Microsoft VS Code\Code.exe',
    "--new-window", "--wait",
    ]
]

When the configuration file is loaded, the above expression “{{ get_env(name="LOCALAPPDATA") }}” expands under Windows for a user with the username “Joe” to “C:\User\Joe\AppData\Local” resulting in:

[app_args]
windows.editor = [
    [
    'C:\User\Joe\AppData\Local\Programs\Microsoft VS Code\Code.exe',
    "--new-window", "--wait",
    ]
]

In general, when you configure Tp-Note to work with your text editor, make sure, that your text editor does not fork! You can check this by launching the text editor from the command line: if the command prompt returns immediately, then the file editor forks the process. On the other hand everything is OK, when the command prompt only reappears at the moment the text editor is closed. Many text editors provide an option to restrain from forking: for example the VScode file editor can be launched with the “--wait” option, Vim with “--nofork” or Kate with “--block”.

However, Tp-Note also works with forking text editors. Although this should be avoided, there is a possible workaround. Observe the following example:

$ TPNOTE_EDITOR="kate" tpnote
/home/getreu/20230714-getreu--Note.md
$ 

In the above example Tp-Note launches the “kate” editor in a forking manner as the command line flag “--block” is missing. Internally the editor process launching returns immediately, leaving Tp-Note without any means to detect when exactly the user closes the editor. Hence, Tp-Note is not able to check if the user has changed the note’s header and no filename synchronization can occur afterwards.

As a workaround, you can manually trigger the filename synchronization after editing with “tpnote --batch "$FILE"”:

FILE=$(tpnote --batch) # Create the new note.
tpnote --view "$FILE"& # Launch Tp-Note's viewer.
kate "$FILE"           # Note, the prompt returns immediatly as the editor forks.
                       # After closing the editor when editing is done...
tpnote --batch "$FILE" # Synchronize the note's filename again.

Whereby “FILE=$(tpnote --batch)” creates the note file, “kate "$FILE"” opens the text editor and “tpnote --batch "$FILE"” synchronizes the filename after editing.

NB: Try to avoid forking at all cost. As mentioned above, most text editors have a command line flag to prevent the process from forking:

TPNOTE_EDITOR="kate --block" tpnote

Register a Flatpak Markdown editor

Flathub for Linux is a cross-platform application repository that works well with Tp-Note. To showcase an example, we will add a Tp-Note launcher for the Mark Text Markdown text editor available as Flatpak package. Before installing, make sure that you have set up Flatpack correctly. Then install the application with:

sudo flatpak install flathub com.github.marktext.marktext

To test, run Mark Text from the command line:

flatpak run com.github.marktext.marktext

Then place a Tp-Note configuration in its search path (e.g.  “~/.config/tpnote/tpnote.toml”) with the following content:

[app_args]
unix.editor = [ [ 'flatpak', 'run', 'com.github.marktext.marktext', ] ]

The structure of this variable is a list of lists. Every item in the outer list corresponds to one entire command line launching a different text editor, here Marktext. When launching, Tp-Note searches through this list until it finds an installed text editor on the system.

Save the modified configuration file. Next time you launch Tp-Note, the Mark Text-editor will open.

Register a console text editor running in a terminal emulator

In this setup Tp-Note launches the terminal emulator which is configured to launch the text editor as child process. Neither process should fork when they start (see above).

Here, some examples you can adjust to your needs and taste:

Tp-Note identifies the note’s markup language by its file extension and renders the content accordingly (see “filename.extensions” variable). For example: the variable “filename.extensions” lists some extensions, that are regarded as Markdown files:

[[scheme]]
name = "default"
[scheme.filename]
extensions = [
  [ "txt", "Markdown" ],
  [ "md", "Markdown" ],
  [ "markdown", "Markdown" ],
  [ "markdn", "Markdown" ],
  [ "mdown", "Markdown" ],
  [ "mdtxt", "Markdown" ],
]

The default file extension for new note files is defined as:

[[scheme]]
name = "default"
[scheme.filename]
extension_default = 'md'

If you prefer rather the file extension “.markdown” for new notes, write a configuration file with:

[[scheme]]
name = "default"
[scheme.filename]
extension_default = 'markdown'

This modification does not change how the note file’s content is interpreted - in this case as Markdown - because both file extensions “.md” and “.markdown” are rendered as “Markdown” according to “filename.extensions”.

When creating a new header for a new or an existing note file, a linguistic language detection algorithm tries to determine in what natural language the note file is authored. Depending on the context, the algorithm processes as input: the header field “title:” or the first sentence of the text body. The natural language detection algorithm is implemented as a template filter named “get_lang”, which is used in various Tera content templates “tmpl.*_content” in Tp-Note’s configuration file. The filter “get_lang” is parametrized by the configuration variable “tmpl.filter.get_lang” containing a list of ISO 639-1 encoded languages, the algorithm considers as potential detection candidates, e.g.:

[[scheme]]
name = "default"
[scheme.tmpl]
filter.get_lang = [ 'en', 'fr', 'de', 'et' ]

As natural language detection is CPU intensive, it is advised to limit the number of detection candidates to 5 or 6, depending on how fast your computer is. The more language candidates you include, the longer the note file creation takes time. As a rule of thumb, with all languages enabled the creation of new notes can take up to 4 seconds on my computer. Nevertheless, it is possible to enable all available detection candidates with the pseudo language code “+all” which stands for “add all languages”:

[[scheme]]
name = "default"
[scheme.tmpl]
filter.get_lang = [ '+all', ]

Once the language is detected with the filter “get_lang”, it passes another filter called “map_lang”. This filter maps the result of “get_lang” - encoded as ISO 639-1 code - to an IETF language tag. For example, “en” is replaced with “en-US” or “de” with “de-DE”. This additional filtering is useful, because the detection algorithm can not figure out the region code (e.g. -US or -DE) by itself. Instead, the region code is appended in a separate processing step. Spell checker or grammar checker like [LTeX] rely on this region information, to work properly.

The corresponding configuration looks like this:

[[scheme]]
name = "default"
[scheme.tmpl]
filter.map_lang = [
    [ 'en', 'en-US', ],
    [ 'de', 'de-DE', ],
]

When the user’s region setting - as reported from the operating system’s locale setting - does not exist in above list, it is automatically appended as additional internal mapping. When the filter map_lang encounters a language code for which no mapping is configured, the input language code is forwarded as it is without modification, e.g. the input fr results in the output fr. Subsequent entries that differ only in the region subtag, e.g. “['en', 'en- GB'], ['en', 'en-US']” are ignored.

Note, that the environment variable “TPNOTE_LANG_DETECTION” - if set - takes precedence over the “tmpl.filter.get_lang” and “tmpl.filter.map_lang” settings. This allows configuring the language detection feature system-wide without touching Tp-Note’s configuration file. The following example achieves the equivalent result to the configuration hereinabove:

TPNOTE_LANG_DETECTION="en-US, fr, de-DE, et" tpnote

If you want to enable all language detection candidates, add the pseudo tag “+all” somewhere to the list:

TPNOTE_LANG_DETECTION="en-US, de-DE, +all" tpnote

In the above example the IETF language tags “en-US” and “de-DE” are retained in order to configure the region codes “US” and “DE” used by the “map_lang” template filter.

For debugging observe the value of “SETTINGS” in the debug log with:

tpnote -d trace -b

If wished for, you can disable Tp-Note’s language detection feature, by deleting all entries in the “tmpl.filter.get_lang” variable:

[[scheme]]
name = "default"
[scheme.tmpl]
filter.get_lang = []

Like above, you can achieve the same with:

TPNOTE_LANG_DETECTION="" tpnote

Be default, the front matter variable names are printed in English when creating new note files from templates. For example the header variable “fm_subtitle” is displayed as “title:” in the note’s header.

This translation relation is defined in the configuration file variable “scheme.tmpl.fm_vars.localization”. Consider the following simplified example:

[[scheme]]
name = "default"
fm_vars.localization = [
    ["fm_title", "title"],
    ["fm_subtitle", "subtitle"],
    ["fm_author", "author"],
    ["fm_date", "date"],
    ["fm_lang", "lang"],
]

To change the natural language of the displayed header variable names, modify the second column of the above table. Example:

[[scheme]]
name = "default"
fm_vars.localization = [
    ["fm_title", "Titel"],
    ["fm_subtitle", "Untertitel"],
    ["fm_author", "Autor"],
    ["fm_date", "Datum"],
    ["fm_lang", "Sprache"],
]

Keep in mind, that the templates do not change! Templates refer to a header variable with an identifier starting with “fm_”, The identifier corresponds to the first column of the above table.

Tp-Note’s core functionality, the management of note file headers and filenames, is markup language agnostic. However, there is one content template “tmpl.annotate_file_content” that generates a hyperlink. The hyperlink syntax varies depending on the markup language. Hence, you should not forget to modify the “tmpl.annotate_file_content” content template, when you change the default markup language defined in “filename.extension_default”.

---
title:    some note
file_ext: rst
---

Sort-tags for new notes are generated with the “tmpl.*_filename” templates. Before changing the sort-tag generation scheme in these templates, make sure to enable the right set of potential sort-tag characters.

In the default scheme, the digits “0”-“9”, all lower case letters and the characters “_”, “-”, “.” are recognized as being part of a sort tag when they appear at the beginning of a filename. This set of characters can be modified with the “filename.sort_tag.extra_chars” configuration variable. If defined, the “filename.sort_tag.separator” (by default “-”) marks the end of a sort tag without being part of it. In addition, one special character “filename.sort_tag.extra_separator” (by default “'”) might be inserted by the filename template directly after the “-” to avoid ambiguity.

The filename synchronization scheme is fully customizable through Tp-Note’s filename templates. To design such a custom scheme, start to set up your synchronization rules in the “tmpl.sync_filename” template. Then adjust all “tmpl.*_filename” templates to comply with these rules. In order to verify your design, check that the following holds for any sequential application of one “tmpl.*_filename” template followed directly by the “tmpl.sync_filename” template: The latter should never change the filename initially set up by any “tmpl.*_filename” template.

Secondly, make sure that in filename templates “tmpl.*_filename”, sort-tags “{{ path | file_sort_tag }}” are never inserted directly. Instead, prepend the sort_tag with “prepend(with_sort_tag=path|file_sort_tag)” to the following expression, e.g.:

{{ fm_title | sanit | prepend(with_sort_tag=path|file_sort_tag) }}

The filter “prepend(with_sort_tag=<...>)” decides whether to insert the “sort_tag.separator="-"” and/or the “sort_tag.extra_separator="'"” characters. These heuristics enable Tp-Note to identify unequivocally sort-tags in filenames, which avoids potential cyclic filename change. Or, in other words: the “tmpl.sync_filname” template must always give the same result, even after repeated application.

To debug your “tmpl.sync_filename” template, create a test note file “test.md” and invoke Tp-Note with “--debug trace” and “--batch”:

tpnote --batch --debug trace test.md

When you are annotating an existing file on disk, the new note file is placed in the same directory by default. To configure Tp-Note to store the new note file in a subdirectory, let’s say “Notes/”, instead, you need to modify the templates “tmpl.annotate_file_filename” and “tmpl.annotate_file_content”:

Replace in “tmpl.annotate_file_filename” the string:

{{ path | file_sort_tag }}

with:

Notes/{{ path | file_sort_tag }}

and in “tmpl.annotate_file_content”:

[{{ path | filename }}](<{{ path | filename }}>)

with:

[{{ path | filename }}](<../{{ path | filename }}>)

Delay the launch of the web browser

By default, Tp-Note launches two external programs: some text editor and a web browser. If wished for, the configuration variable “viewer.startup_delay” allows delaying the launch of the web browser some milliseconds. This way the web browser window will always appear on top of the editor window. A negative value delays the start of the text editor instead.

Change the way how note files are rendered for viewing

Besides its core function, Tp-Note comes with several built-in markup renderer and viewer, allowing to work with different markup languages at the same time. The configuration file variable “filename.extension” determine which markup renderer is used for which note file extension. Depending on the markup language, this feature is more or less advanced and complete: Markdown (cf. “Markdown”) is best supported and feature complete: It complies with the Common Mark specification. The ReStructuredText renderer (cf. “Restructuredtext”) is quite new and still in experimental state. For all other supported markup languages Tp-Note provides a built-in markup source text viewer (cf. “PlainText”) that shows the note as typed (without markup), but renders all hyperlinks to make them clickable. In case none of the above rendition engines suit you, it is possible to disable the viewer feature selectively for some particular note file extensions: just associate these extensions with the “PlainTextNoViewer” renderer. If you wish to disable the viewer feature overall, set the variable “arg_default.edit = true”.

Change the HTML rendition template

After the markup rendition process, Tp-Note’s built-in viewer generates its final HTML rendition through the customizable HTML templates “tmpl_html.viewer”, “tmpl_html.viewer_error” and “tmpl_html.exporter”. Unlike content templates and filename templates, all HTML templates escape HTML critical characters in variables by default. To disable escaping for a specific variable, add the “safe” filter in last position of the filter chain. Please note, that in general, the “safe” filter is only recommended directly after the “to_html” and the “markup_to_html” filters, because these handle critical input by themselves. The following code example, inspired by the “tmpl_html.viewer” template, illustrates the available variables:

[tmpl_html]
viewer = '''
{%- set ext = fm_file_ext | default(value=extension_default ) -%}
<!DOCTYPE html>
<html lang="{{ fm_lang | default(value='en') }}">
<head>
<meta charset="utf-8">
<title>{{ fm_title }}</title>
<link rel="stylesheet" href="{{ viewer_doc_css_path }}">
<link rel="stylesheet" href="{{ viewer_highlighting_css_path }}">
  </head>
  <body>
  <pre class="doc-header">{{ doc_fm_text }}</pre>
  <hr>
  <div class="doc-body">
    {{ doc_body_text | markup_to_html(extension=ext) | safe }}
  </div>
  <script>{{ viewer_doc_js | safe }}</script>
</body>
</html>
'''

Specifically:

Alternatively, the header enclosed by “<pre>...</pre>” can also be rendered as a table:

  <table class="fm">
    <tr>
    <th class="fmkey">title:</th>
    <th class="fmval"><b>
        {{ fm_title| default(value='') | to_html | safe }}</b>
    </th>
  </tr>
    <tr>
    <th class="fmkey">subtitle:</th>
    <th class="fmval">
        {{ fm_subtitle | default(value='') | to_html | safe }}
    </th>
  </tr>
  {% for k, v in fm_all| remove(key='fm_title')|
                         remove(key='fm_subtitle')|
  %}
    <tr>
    <th class="fmkeygrey">{{ k }}:</th>
    <th class="fmvalgrey">{{ v | to_html | safe }}</th>
  </tr>
  {% endfor %}
  </table>

The error page template “tmpl_html.viewer_error” (see below) does not provide “fm_*” variables, because of possible header syntax errors. Instead, the variable “{{ doc_error }}” contains the error message as raw UTF-8 and the variable “{{ doc_text | markup_to_html | safe }}” the HTML rendition of the text source with clickable hyperlinks:

[tmpl_html]
viewer_error = '''
<!DOCTYPE html>
<html lang=\"en\">
<head>
<meta charset=\"UTF-8\">
<title>Syntax error</title>
</head>
<body>
<h3>Syntax error</h3>
<p> in note file: <pre>{{ path }}</pre><p>
<div class=\"note-error\">
<hr>
<pre>{{ doc_error }}</pre>
<hr>
</div>
{{ doc_text | markup_to_html | safe }}y
<script>{{ viewer_doc_js | safe }}</script>
</body>
</html>
'''

Customize the built-in HTML exporter

Customizing Tp-Note’s HTML export function works the same way as customizing the built-in viewer. There are some slight differences though: The role of the “tmpl_html.viewer” template - discussed above - is taken over by the “tmpl_html.exporter” template:

[tmpl_html]
exporter = '''
{%- set ext = fm_file_ext | default(value=extension_default ) -%}
<!DOCTYPE html>
<html lang="{{ fm_lang | default(value='en') }}">
<head>
<meta charset="utf-8">
<title>{{ fm_title }}</title>
<style>
{{ exporter_doc_css | safe }}
{{ exporter_highlighting_css | safe }}
</style>
</head>
<body>
  <pre class="doc-header">{{ doc_fm_text }}</pre>
  <hr>
  <div class="doc-body">
    {{ doc_body_text| markup_to_html(extension=ext) | safe }}
  </div>
</body>
</html>
'''

In this template the same Tera variables as in “tmpl_html.viewer” are available, with one exception “{{ note_js }}”, which does not make sense in this context. As the exporter prints possible rendition error messages on the console, there is no equivalent to the “tmpl_html.viewer_error” template. Note, in contrast to the previous “tmpl_html.viewer” example, the source code highlighting CSS code is now embedded into the HTML output with:

<style>
{{ exporter_doc_css | safe }}
{{ exporter_highlighting_css | safe }}
</style>

Note, the “safe” filter disables the escaping of critical characters in the CSS input. We have no security concerns in this context, because we have full control over the CCS input coming from the configuration file variables “tmpl_html.exporter_doc_css” and “tmpl_html.exporter_highlighting_theme”.

Once the note is rendered into HTML, Tp-Note’s internal HTTP server connects to a random port at the “localhost” interface where the rendition is served to be viewed with a web browser. Tp-Note’s configuration file contains a list “app_args.unix.browser” with common web browsers and their usual location on Unix like operating systems. For other systems consult “app_args.windows.browser” and “app_args.macos.browser”. This list is executed top down until a web browser is found and launched. If you want to view your notes with a different web browser, simply modify the “app_args.unix.browser” list and put your favourite web browser on top. Alternatively, you can set the “TPNOTE_BROWSER” environment variable (cf. examples in the chapter ENVIRONMENT_VARIABLES below).

In case none of the listed browsers can be found, Tp-Note switches into a fallback mode with limited functionality, where it tries to open the system’s default web browser. A disadvantage is, that in fall back mode Tp-Note is not able to detect when the user closes the web browser. This might lead to situations, where Tp-Note’s internal HTTP server shuts down to early. In order to check if Tp-Note finds the selected web browser as intended, invoke Tp-Note with “tpnote --debug debug --popup --view”.

The content of a new note is composed by one of Tp-Note’s internal customizable templates, hence the name Tp-Note, where Tp stands for “template”. Which of the internal templates is applied depends on the context in which Tp-Note is invoked: e.g. the template for clipboard text input is called “tmpl.from_clipboard_content”. If the clipboard contains text with a YAML header, the template “tmpl.from_clipboard_yaml_content” is used.

In total, there are 5 different “tmpl.*_content” templates:

In general, the templates are designed in a way, that the text input stream - usually originating from the clipboard - ends up in the body of the note file, whereas the environment - such as the username - ends up in the header of the note file.

Once the content of the new note is set by one of the content templates, another template type comes into play: the so-called filename template. Each content template has a corresponding filename template, e.g.:

As the name suggests, the role of a filename template is to determine the filename of the new note. This is done by evaluating (deserializing) it’s YAML header. The values of the note’s YAML header fields are can be accessed in filename templates through various “{{ fm_<key> }}” dynamically created template variables. For example the value of the YAML header field “title:” can be accessed with “{{ fm_title }}”. Once the filename is set, Tp-Note writes out the new note on disk.

Most of the above templates are dedicated to the creation of new note files. However, two of them have a special role: prepend header to text file and synchronize filename:

Note, that in the operation mode synchronize filename, the header data overwrites the filename of the note, whereas in the operation mode prepend header the filename data is copied into the new prepended header. Keep in mind, that even in the latter mode the filename might change slightly. This is because after the header creation with the “tmpl.from_text_file_content” template, the “tmpl.from_text_file_filename” template is applied, which might cause a slight filename modification due to its sanitization filters (cf. “sanit()” in the section Template filters).

You can disable the prepend header feature by setting the configuration file variable “arg_default.add_header = false”. To disable all filename synchronization, set “arg_default.no_filename_sync = true”. This guarantees, that Tp-Note will never change neither the filename nor the YAML header of an existing file.

For a more detailed description of templates and their defaults, please consult the “const” definitions in Tp-Note’s source code files “config.rs” and “note.rs” in the directory “tpnote-lib/src/”.

All Tera template variables and functions can be used within Tp-Note’s templates. For example “{{ get_env(name='LANG') }}' gives you access to the”LANG’ environment variable.

In addition, Tp-Note defines the following variables:

The following “{{ fm_* }}” variables are typically generated, after a content template was filled in with data: For example a field named “title:” in the content template “tmpl.from_dir_content” will generate the variable “fm_title” which can then be used in the corresponding “tmpl.from_dir_filename” filename template. “{{ fm_* }}” variables are generated dynamically. This means, a YAML front-matter variable “foo:” in a note will generate a “{{ fm_foo }}” template variable. On the other hand, a missing “foo:” will cause “{{ fm_foo }}” to be undefined. Please note, that the header variables may be localized, e.g. “Untertitel:”. Nevertheless, in templates always use the English version, e.g. “fm_subtitle”.

It is to be observed that “{{ fm_* }}” variables are only available in filename templates and in the “tmpl.from_clipboard_yaml_content” content template.

Important: there is no guarantee, that any of the above “{{ fm_* }}” variables are defined! Depending on the last content template result, certain variables might be undefined. Please take into consideration, that a defined variable might contain the empty string “""”. Creating a new note file with a content template, the note’s header is parsed into “{{ fm_* }}” variables. The latter are then type checked according configurable rules. The rules are defined in “tmpl.filter.assert_precondition”

For a more detailed description of the available template variables, please consult the “const” definitions in Tp-Note’s source code file “note.rs”.

In addition to Tera’s built-in filters, Tp-Note comes with some additional filters, i.e.: “append(newline=true)”, “append(with=...)”, “cut”, “file_copy_counter”, “file_ext”, “file_name”, “file_sort_tag”, “file_stem”, “get_lang”, “heading”, “insert(key=..., value=...)”, “link_dest”, “link_text”, “link_title”, “map_lang”, “prepend”, “prepend(newline=true)”, “prepend(with=...)”, “prepend(with_sort_tag=...)”, “remove(key=)” “sanit”, “to_html”, “to_yaml”, “to_yaml(key=...)”, “to_yaml(tab=...)” and “trim_file_sort_tag”.

A filter is always used together with a variable. Here are some examples:

Tp-Note distinguishes two template types: content templates are used to create the note’s content (front-matter and body) and the corresponding filename templates “tmpl.*_filename” are used to calculate the note’s filename. By convention, content templates appear in the configuration file in variables named “tmpl.*_content”.

Strings in the front matter section of content templates are YAML encoded. Therefore, all variables used in the front-matter must pass an additional “to_yaml()”-filter. For example, the variable “{{ dir_path | file_stem() }}” becomes “{{ dir_path | file_stem() | to_yaml(key='title') }}” or, shorter: “{{ dir_path | file_stem | to_yaml(key='title') }}”.

When given with a key, the “to_yaml(key='...')” filter accepts any input type, whereas the short form “to_yaml()” requires an “Value::Object” type as input. The latter is often followed be the “append(newline=true)” filter appending a newline.

By convention, filename templates appear in the configuration file in variables named “tmpl.*_filename”. When a content template creates a new note, the corresponding filename template is called afterwards to calculate the filename of the new note. Please note that, the filename template “tmpl.sync_filename” has a special role as it synchronizes the filename of existing note files. Besides this, as we are dealing with filenames we must guarantee, that the filename templates produce only file system friendly characters. For this purpose Tp-Note provides the additional Tera filter “sanit”:

The “sanit()” filter transforms a string in a file system friendly from. This is done by replacing forbidden characters like “?” and “\\” with “_” or space. This filter can be used with any variable, but is most useful with filename templates. For example, in the “tmpl.sync_filename” template, we find the expression “{{ subtitle | sanit }}”. Note that the filter recognizes strings that represent a so-called dot file name and treats them a little differently by prepending them with an apostrophe: a dot file is a file whose name starts with “.” and that does not contain whitespace. It may or may not end with a file extension. The apostrophe preserves the following dot from being filtered.

The “prepend(with_sort_tag=<...>” filter is similar to the “prepend(with=<...>” filter, with two exceptions:

Both separators guarantee that the end of a sort-tag is detected unequivocally. For example, when the input string starts with a digit “0123456789” or “-_”, the string is prepended with -', e.g. “1-The Show Begins” becomes “'1-The Show Begins”. The “prepend(with_sort_tag=<...>)” filter must be applied to the first variable, e.g.  “{{ fm_title | sanit | prepend(with_separator=path|file_sort_tag )}”. This way, it is always possible to univocally distinguish the sort-tag from the rest of the filename. Note, the default sort-tag separators can be changed with the configuration variables “filename.sort_tag.separator” and “filename.sort_tag.extra_separator”. For more details please consult the Customize the filename synchronization scheme chapter.

In filename templates most variables must pass the “sanit” filter. Exception to this rule are sort-tag expressions like “{{ path | file_sort_tag }}” and “{{ dir_path | file_sort_tag }}”. As the latter are guaranteed to contain only the file system friendly characters “0123456789 -_”, no additional filtering is required. Please note, that in this case a “sanit”-filter would needlessly restrict the value range of sort-tags because they may contain characters, which the “sanit”-filter screens out when they appear in leading or trailing position. For this reason one must not use the “sanit”-filter together with “{{ path | file_sort_tag }}” or “{{ dir_path |file_sort_tag }}”.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 licence, shall be dual licensed as above, without any additional terms or conditions. Licensed under the Apache Licence, Version 2.0 (the “Licence”); you may not use this file except in compliance with the Licence.