Tp-Note: fast note taking with templates and filename synchronization

Organize your notes with your favourite editor and markup-language

Jens Getreu


Table of Contents

1. How students take notes
1.1. Fast start note-taking (when the lecture starts)
1.2. Taking notes about a file
1.3. Document the download location of a local file
1.4. Bookmark and comment a hyperlink
1.5. Copy a page from a book
1.6. Best practice
1.7. Note taking for system administrators (and console lovers)
2. How it works: Organize your files and notes with sort-tags
3. Installation
3.1. Minimum setup with no file manager integration
3.2. Usage of the minimum setup
3.3. Troubleshooting
3.4. Optional customization
4. Optional integration with your file manager
4.1. Windows file explorer configuration
4.2. Linux file manager configuration

Markup languages like Markdown [1] are perfectly suited for fast note-taking. Type your notes with your favourite text editor and observe live the rendered text in you web browser.

Tp-Note helps you to quickly get started writing notes with its powerful template system. If you like to keep your notes next to your files and you care about expressive filenames, then Tp-Note might be the tool of your choice. As Tp-Note synchronizes the note’s filename with its document title, you will find back your notes easily.

Tp-Note is available for Linux, Windows and iOS. This manual illustrates its main use-cases and how to get started:

  1. Fast start note-taking (when the lecture starts).

  2. Take a note about an existing or downloaded file.

  3. Bookmark and comment a hyperlink.

  4. Copy and annotate a page from a book.

  5. Best practise.

  6. Note taking for system administrators.

If you want to customize Tp-Note with your own templates or if you want to use another markup language than Markdown, please consult the [man-page] for more technical details. It also explains how to change Tp-Note’s default text editor.

The project is hosted on Github: getreu/tp-note. The project’s webpage is on http://blog.getreu.net. The documentation of this project is dived into tow parts:

1. How students take notes

A fellow student still uses paper and pen. I ask her why, and she replied I can better concentrate. My computer distracts me. I will do all other things, but not listening..

This is certainly true. As far as I am concerned, I am not good at logistics. For me having all documents and notes in one little machine is a blessing.

The following sections illustrate how to work with Tp-Note with my most common workflows.

1.1. Fast start note-taking (when the lecture starts)

Figure 1. The folder in which the new note will be created.

The folder in which the new note will be created.

Alternatively you can open the folder where you want to create a new note and right-click on some empty white space.

Figure 2. The new unmodified note created by template on disk

The new unmodified note created by template on disk

Figure 3. The new unmodified note created by template

The new unmodified note created by template

Figure 4. Change the title

Change the title

Figure 5. Add some text

Add some text

Figure 6. The new note file on disk after closing the editor

The new note file on disk after closing the editor

Note

Before and after launching the editor Tp-Note renames the file to be in sync with the note’s metadata (i.e. title and subtitle). For more details see How it works: Organize your files and notes with sort-tags.

1.2. Taking notes about a file

Figure 7. We want to take a note about a pdf

We want to take a note about a pdf

Figure 8. The new unmodified note created automatically

The new unmodified note created automatically

The source-code of the note shows the link with its target. The left-click, opens the .odt document.

---
title:      "Lied-Das_ist_mein_Teddybär - Lernstationen - Arbeitsblätter.odt"
subtitle:   "Note"
author:     "getreu"
date:       "March 10, 2020"
lang:       "en_GB.UTF-8"
---

[03-Lied-Das_ist_mein_Teddybär - Lernstationen - Arbeitsblätter.odt](<03-Lied-Das_ist_mein_Teddybär - Lernstationen - Arbeitsblätter.odt>)

Figure 9. Annotate

Annotate

Figure 10. The new note file on disk after closing the editor

The new note file on disk after closing the editor

1.3. Document the download location of a local file

The approach is similar to what we have seen in the previous chapter:

Figure 11. Copy the location of the download page as Markdown

Copy the location of the download page as Markdown

Note: for convenience I use in this example the Firefox browser addon Copy Selection as Markdown to copy the hyperlink. If this addon is not available, you can also copy the URL directly from the search bar.

Figure 12. Select the file to annotate and start Tp-Note

Select the file to annotate and start Tp-Note

Figure 13. The new unmodified note created automatically

The new unmodified note created automatically

The source-code of the note shows the links with their targets.

---
title:      "ascii-hangman.exe"
subtitle:   "URL"
author:     "getreu"
date:       "2020-08-27"
lang:       "en_GB.UTF-8"
---

[ascii-hangman.exe](<ascii-hangman.exe>)

[ASCII-Hangman - hangman game for children with ASCII-art rewarding](<https://blog.getreu.net/projects/ascii-hangman/#distribution>)

Figure 14. The new note file on disk after closing the editor

The new note file on disk after closing the editor

1.4. Bookmark and comment a hyperlink

Figure 15. Copy a link in Markdown format

Copy a link in Markdown format

To copy a link in Markdown format a browser addon is needed. I recommend the addons Copy as Markdown and Copy Selection as Markdown available for Firefox.

Figure 16. Right-click on or in the new note’s destination folder and start Tp-Note

Right-click on or in the new note’s destination folder and start Tp-Note

Figure 17. The new unmodified note created automatically

The new unmodified note created automatically

The source code of the note shows the link target:

---
title:      "Rustacean Station"
subtitle:   "URL"
author:     "getreu"
date:       "March 10, 2020"
lang:       "en_GB.UTF-8"
---

[Rustacean Station](<https://rustacean-station.org/>)

In this example we copied only one Markdown-link Rustacean Station. Furthermore, Tp-Note allows you also to insert a list of Markdown links in a template. For example with Copy as Markdown you could copy a link list of all open tabs. In this case, Tp-Note would retain only the name of the first link as document title, whereas the whole link-list would appear in the body of the note.

Figure 18. Annotate

Annotate

Figure 19. The new note file on disk after closing the editor

The new note file on disk after closing the editor

1.5. Copy a page from a book

Figure 20. Copy some chapters

Copy some chapters

Figure 21. Right-click on or in the new note’s destination folder and start Tp-Note

Right-click on or in the new note’s destination folder and start Tp-Note

Figure 22. The new unmodified note created automatically

The new unmodified note created automatically

The source code of the note shows the completed template:

---
title:      "Winston kept his back turned to the telescreen"
subtitle:   "Note"
author:     "getreu"
date:       "2020-03-23"
lang:       "en_GB.UTF-8"
---

Winston kept his back turned to the telescreen. It was safer, though, as he well
knew, even a back can be revealing. A kilometer away the Ministry of Truth, his
place of work, towered vast and white above the grimy landscape...

In this example we copied only text. Tp-Note suggests the first sentence as title. This can be changed before saving as illustrated above. Here we just save and observe the file on the disk.

Figure 23. The new note file on disk after closing the editor

The new note file on disk after closing the editor

1.6. Best practice

Tp-Note’s greatest advantage is it’s flexibility. It easily integrates with your workflow. As people work differently, there is no best usage either. Nevertheless, after having used Tp-Note for some months now, here my personal preferences and configuration:

My favourite Markdown editors at the moment are Mark Text and Typora. I like their clean and simple interface helping me to stay focused on the content while writing.[2]

When copying extracts from a web-page, I often need to preserve its hyperlinks. For this, the Firefox browser addon Copy Selection as Markdown is very handy. It precedes the copied extract with a hyperlink to the origin of the webpage. When TP-Note reads the extract from the clipboard, it uses the first Markdown hyperlink it can find for composing the note’s title and its filename on disk. This is why the web page’s name ends up automatically in the note’s title and filename. Here a sample work flow:

Figure 24. A webpage to copy extracts from

A webpage to copy extracts from

Figure 25. Copy Selection as Markdown

“Copy Selection as Markdown”

Figure 26. Right-click on or in the new note’s destination folder and start Tp-Note

Right-click on or in the new note’s destination folder and start Tp-Note

Figure 27. The new template generated note opened with Typora

The new template generated note opened with Typora

Figure 28. The new note file on disk after closing the editor

The new note file on disk after closing the editor

Note, no content or filename was edited manually in this example. Tp-Note takes care of interpreting the clipboard’s content and generating the file on disk.

1.7. Note taking for system administrators (and console lovers)

As Tp-Note makes extensive use of the clipboard, it mainly targets desktop systems running a graphical environment. But also when working on the console Tp-Note can be useful. Here some typical workflows:

  • Document a downloaded file:

    Download the file i3-extensions.zip:

    wget "http://blog.getreu.net/_downloads/i3-extensions.zip"
    

    Document from where you downloaded the file:

    echo  "[download](<http://blog.getreu.net/_downloads/i3-extensions.zip>)" | tp-note i3-extensions.zip
    

    This creates the file i3-extensions.zip--URL.md with the following content:

    ---
    title:      "i3-extensions.zip"
    subtitle:   "URL"
    author:     "getreu"
    date:       "2020-09-03"
    lang:       "en_GB.UTF-8"
    ---
    
    [i3-extensions.zip](<i3-extensions.zip>)
    
    [download](<http://blog.getreu.net/_downloads/i3-extensions.zip>)
    
  • Download a webpage, convert it to Markdown and insert the result into a Tp-Note file. The note’s title is the name of the first hyperlink found in the webpage.

    curl 'https://blog.getreu.net' | pandoc -f html -t markdown_strict | tp-note
    
  • The same as above, but the note’s title is the same as the webpage’s title:

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

    creates the note file 20200910-Jens\ Getreu\'s\ blog.md with the webpage’s content.

  • Generate note for a given content with YAML header:

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

    creates the file 20200910-Todo.mdtxt with the content:

    ---
    title:      "Todo"
    subtitle:   ""
    author:     "getreu"
    date:       "2020-09-13"
    lang:       "en_GB.UTF-8"
    file_ext:   "mdtxt"
    ---
    
    nothing
    
  • Reformat the header of a note file:

    mv "20200921-My Note.md" "20200921-My Note-(1).md"
    cat "20200921-My Note-(1).md" | tp-note --batch
    

    creates the file 20200921-My Note.md with a rearranged header and the same body.

  • Launch, for once, a different file editor.
    The external file editor, Tp-Note uses, is defined in the configuration file and can be changed there. If you want to use a different file editor just for one-shot, type:

    nvim "$(tp-note --batch)"
    
  • Create a new note overwriting the template’s default for subtitle:

    cd dev
    echo -e "---\nsubtitle: Draft\n---\n# Draft" | tp-note
    

    creates the note file 20200925-dev--Draft.md with the content:

    ---
    title:      "dev"
    subtitle:   "Draft"
    author:     "getreu"
    date:       "2020-09-25"
    lang:       "en_GB.UTF-8"
    ---
    
    # Draft
    
  • Synchronize filename with header of all note files in the current directory:

    find . -type f -name "*.md" -exec tp-note --batch {} \; >/dev/null
    

2. How it works: Organize your files and notes with sort-tags

Consider the following Tp-Note-file:

20151208-Make this world a better place--Suggestions.md

The filename has 4 parts:

{{ fm_sort_tag }}-{{ fm_title }}--{{ fm_subtitle }}.{{ fm_file_ext }}

A so called sort-tag is a numerical prefix at the beginning of the filename. It is used to order files and notes in the file system. Besides numerical digits, a sort-tag can be any combination of 0123456789-_ and is usually used as:

  • chronological sort-tag

      20140211-Reminder.doc
      20151208-Manual.pdf
    
  • or as a sequence number sort-tag.

      02-Invoices
      08-Tax documents
      09_02-Notes
    

The figures below illustrate organizing files with *sort-tags".

Figure 29. Folders with sequence number sort-tag

Folders with sequence number sort-tag

Figure 30. File with chronological sort-tag

File with chronological sort-tag

When Tp-Note creates a new note, it prepends automatically a chronological sort-tag of today. The {{ fm_title }} part is usually derived from the parent directory’s name omitting its own sort-tag.

3. Installation

Depending on the operating system, the installation process is more or less automated and can be divided up into two steps:

  1. Minimum setup with no file manager integration
    This step consists of downloading Tp-Note’s binary and copying it to your hard-disk. See section Distribution on Tp-Note’s project page for a list of available packages and binaries.

  2. Optional integration with your file manager.

At the moment of this writing, an installer automating steps 1. and 2. is available for Windows only. Packages for Debian Linux and Ubuntu help you with step 1. For other operating systems check section Distribution for precompiled binaries or build Tp-Note yourself.

3.1. Minimum setup with no file manager integration

Tp-Note’s template engine can be tested and used without window manager integration. This section shows a minimum setup to get started quickly.[3]

  • Windows

    Download the tp-note executable for Windows [4] and place it on your desktop.

  • Linux

    Download the Tp-Note-binary for Linux and place it on your Desktop:

    > cd ~/Desktop
    > wget https://blog.getreu.net/projects/tp-note/_downloads/x86_64-unknown-linux-gnu/release/tp-note
    > chmod 755 tp-note
    

A new Tp-Note-icon appears on your desktop.

3.2. Usage of the minimum setup

To create a new note, either double-click on the Tp-Note-icon, or drag a folder or file and drop it on the to-note-icon. This opens an editor with your new note.

For more comfort, I recommend integrating Tp-Note into the file-manager’s context menu. See section Optional integration with your file manager for more details. There you also will find a list of tested Markdown-editors, if you wish to use one. Tp-Note works with every Unicode text editor and Markdown-editor (see section Optional customization and man-page for more details).

Tp-Note’s note-files can be converted into e.g. .docx, .odt, .html with Pandoc and then printed.

3.3. Troubleshooting

3.3.1. Incompatible configuration files

While upgrading Tp-Note, new features may cause a change in Tp-Notes’s configuration file structure and the program fails to start with an error message. Please consult the section Upgrading in the project’s Readme document for more information about incompatible configuration files.

3.3.2. Debugging on Windows

When you see only Chinese characters in notepad, update Windows to the latest version or install Notepad++.

Display Tp-Note’s error messages:

  1. Open the command-prompt: Click on Windows-Start, type cmd and [Enter].

  2. Type:

    Desktop\tp-note.exe -d >Desktop\debug.txt 2>&1
    

    This creates the file debug.txt on your desktop. Open the file and scroll to the end.

3.3.3. Debugging on Linux

Display Tp-Note’s error messages:

  1. Open a console and change to the directory where you saved the Tp-Note-executable.

  2. Type:

    > tp-note -d 2>&1 | less
    

3.4. Optional customization

  • Your preferred markup language is not Markdown, but ReStructuredText, T2t, Textile, Wiki, Mediawiki or Asciidoc? Change it!

    Please refer to Tp-Note’s man-page to learn how to change its templates in the configuration file.

  • Your preferred text editor is not Notepad? Change it![5]

    Note-taking with Tp-Note is more fun with a good markup (Markdown) text editor, although any Unicode text editor will do (even Notepad >= Windows 10-update 1903). Tp-Note is preconfigured to work with:

    Please refer to Tp-Note’s man-page to learn how to register your text editor in Tp-Note’s configuration file.

  • You prefer working in a desktop environment instead of working on a shell?

    Read the following section Optional integration with your file manager to learn how to configure your file manager’s context menu to launch Tp-Note.

4. Optional integration with your file manager

This section shows how to integrate Tp-Note in the context menu of your file manager. The context menu appears, when you click right on a file icon, on a directory icon or on the white space in between (cf. figure below). In the following we will configure the file-manager to launch Tp-Note with the path to the selected icon.

Figure 31. Tp-note in the context-menu (right-click menu)

Tp-note in the context-menu (right-click menu)

4.1. Windows file explorer configuration

Tp-Note is distributed with a Microsoft Windows Installler package tp-note-x.x.x-x86_64.msi, which automates the following key registration. Omit this section if you have installed Tp-Note through this .msi package!

  1. Make the directory C:\Windows\tp-note\bin\ and move tp-note.exe into it.

  2. Open the notepad text editor and paste the following registry-key into it.

     Windows Registry Editor Version 5.00
    
     [HKEY_CLASSES_ROOT\Directory\Background\shell\New Tp-Note]
    
     [HKEY_CLASSES_ROOT\Directory\Background\shell\New Tp-Note\command]
     @="\"C:\\Program Files\\tp-note\\bin\\tp-note.exe\""
    
     [HKEY_CLASSES_ROOT\*\OpenWithList\tp-note.exe]
     @=""
    
     [HKEY_CLASSES_ROOT\SystemFileAssociations\.md\shell\edit.tp-note.exe]
     @="Edit Tp-Note"
    
     [HKEY_CLASSES_ROOT\SystemFileAssociations\.md\shell\edit.tp-note.exe\command]
     @="\"C:\\Program Files\\tp-note\\bin\\tp-note.exe\" \"%1\""
    
     [HKEY_CLASSES_ROOT\SystemFileAssociations\.md\shell\view.tp-note.exe]
     @="View Tp-Note"
    
     [HKEY_CLASSES_ROOT\SystemFileAssociations\.md\shell\view.tp-note.exe\command]
     @="\"C:\\Program Files\\tp-note\\bin\\tp-note.exe\" \"-v\" \"%1\""
    
  3. Save the file as:

    • File name: tp-note.reg

    • Save as type: All files

    • Encoding: UTF-16 LE

  4. Double-click on tp-note.reg and confirm several times.

  5. Assign tp-note as default application for .md-files

    Figure 32. Click-right on .md file to open file properties

    Click-right on .md file to open file properties

    Figure 33. Press Change … and choose tp-note

    Press “Change …” and choose “tp-note”

4.2. Linux file manager configuration

To simplify the configuration we first place the binary Tp-Note in our $PATH:

> cd /usr/local/bin
> sudo wget https://blog.getreu.net/projects/tp-note/_downloads/x86_64-unknown-linux-gnu/release/tp-note
> sudo chmod 755 tp-note

Debian and Ubuntu user can also download [Debian/Ubuntu package] and install it with:

> sudo dpkg -i tp-note_X.X.X_amd64.deb

4.2.1. Configure Thunar’s custom actions

Most file-manager allow extending the context menu. As an example, the following images show the configuration of the Thunar-file-manger.

4.2.1.1. Add context menu entry: Edit Tp-Note

In Thunar’s menu go to:

Edit -> Configure custom actions...

Figure 34. Thunar’s custom action configuration

Thunar’s custom action configuration

Figure 35. Edit custom action

Edit custom action

Figure 36. Appearance Condition

Appearance Condition

Figure 37. Thunar’s custom action configuration with Tp-Note

Thunar’s custom action configuration with Tp-Note

4.2.1.2. Add context menu entry: View Tp-Note

The following context menu entry allows us to view the rendered note in the system’s default web browser. This is very handy when your note contains hyperlinks.

In Thunar, we add a custom action the same way as we did before:

Figure 38. Edit custom action

Edit custom action

Figure 39. Appearance Condition

Appearance Condition

4.2.2. Configure Thunar’s custom actions system-wide

Alternatively, instead of manually adding custom actions for each user, you can do this system-wide:

sudo nano /etc/xdg/Thunar/uca.xml

Search for </actions> and replace it with:

<action>
        <icon>accessories-text-editor</icon>
        <name>Tp-Note</name>
        <command>tp-note %f</command>
        <description>Tp-Note</description>
        <patterns>*</patterns>
        <directories/>
        <audio-files/>
        <image-files/>
        <other-files/>
        <text-files/>
        <video-files/>
</action>
<action>
        <icon>accessories-text-editor</icon>
        <name>Tp-Note View</name>
        <command>tp-note -v %f</command>
        <description>Tp-Note View</description>
        <patterns>*.md;*.rst</patterns>
        <text-files/>
</action>
</actions>

The change becomes effective only after the user deletes his own configuration file in ~/.config/Thunar/uca.xml.

Optional bonus: add a menu entry Download webpage as Markdown

In addition to the above, the following adds a context menu entry for fast downloading and converting a webpage to a Markdown Tp-Note file.

First install some helper programs:

sudo apt install xclip curl pandoc

Then edit the system-wide Thunar configuration file:

sudo nano /etc/xdg/Thunar/uca.xml

Search for </actions> and replace it with:

<action>
    <icon></icon>
    <name>Download URL here</name>
    <command>bash -c 'curl $(xclip -o)| pandoc --standalone -f html -t markdown_strict+yaml_metadata_block+pipe_tables | tp-note  %F'</command>
    <description>Download URL here</description>
    <patterns>*</patterns>
    <directories/>
</action>
</actions>

Again, the change becomes effective only after the user deletes his own configuration file in ~/.config/Thunar/uca.xml.

4.2.3. Configure Pcmanfm’s custom actions system-wide

Pcmanfm is the default file-manager in Lubuntu and in Raspbian on the Raspberry Pi.

Create the configuration file:

sudo nano /usr/local/share/file-manager/actions/tp-note.desktop

with the following content:

[Desktop Entry]
Type=Action
Name[en]=Tp-Note
Tooltip=Tp-Note
Icon=package-x-generic
Profiles=profile-zero;

[X-Action-Profile profile-zero]
Name[en]=Default profile
Exec=tp-note %f

The above creates the custom context-menu item Tp-Note.

4.2.3.1. Note viewer

Create the configuration file:

sudo nano /usr/local/share/file-manager/actions/tp-note-view.desktop

with the following content:

[Desktop Entry]
Type=Action
Name[en]=Tp-Note View
Tooltip=Tp-Note View
Icon=package-x-generic
Profiles=profile-zero;

[X-Action-Profile profile-zero]
Name[en]=Default profile
Exec=tp-note -v %f

The above creates the custom context-menu item Tp-Note View.



[1] Tp-Note is preconfigured to work with many well-known external text editors: e.g.: code, atom, retext, geany, gedit, mousepad, leafpad, nvim-qt, and gvim under Linux and notpad++ and notepad under Windows. To register your own text editor, please consult the man-page. For best user experience, I recommend text editors with internal markup previewer.

[2] If you use Typora, make sure to install a recent version (version >=0.9.89).

[3] Please also consult the section Installation in the projects Readme-document to learn how to install a complete setup.

[4] Versions for other operating systems and a Debian package are available here.

[5] Tp-Note is preconfigured to work with many well-known external text editors: e.g.: code, atom, retext, geany, gedit, mousepad, leafpad, nvim-qt, and gvim under Linux and notpad++ and notepad under Windows. To register your own text editor, please consult the man-page. For best user experience, I recommend text editors with internal markup previewer.