Organize your notes with your favourite editor and markup-language
Table of Contents
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:
Fast start note-taking (when the lecture starts).
Take a note about an existing or downloaded file.
Bookmark and comment a hyperlink.
Copy and annotate a page from a book.
Best practise.
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:
User manual
Unix man-page (more technical)
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.
Alternatively you can open the folder where you want to create a new note and right-click on some empty white space.
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.
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>)
The approach is similar to what we have seen in the previous chapter:
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.
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>)
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.
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.
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.
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:
Addon for Firefox: Copy Selection as Markdown
Integration with you file-manager as described below.
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:
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.
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.mdwith 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.mdwith 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.mdtxtwith 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.mdwith 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.mdwith 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
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".
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.
Depending on the operating system, the installation process is more or less automated and can be divided up into two steps:
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.
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.
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.
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.
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.
When you see only Chinese characters in notepad, update Windows to the latest version or install Notepad++.
Display Tp-Note’s error messages:
Open the command-prompt: Click on Windows-Start, type
cmdand [Enter].Type:
Desktop\tp-note.exe -d >Desktop\debug.txt 2>&1
This creates the file
debug.txton your desktop. Open the file and scroll to the end.
Your preferred markup language is not Markdown, but ReStructuredText, Asciidoc, T2t, Textile, Wiki* or Mediawiki? Change it!
Tp-Note’s core function is a template system and as such it is markup language agnostic. The default templates largely abstain from markup specific code, which makes it easy to switch the default new note’s markup language. Please refer to Tp-Note’s man-page to learn how to change its templates in the configuration file.
In addition, Tp-Note comes with a build in note viewer which is optional and independent from its core functionality. When Tp-Note opens a note file, it choses depending on the file extension which Renderer to launch for which markup language. It is possible to change this association in Tp-Note’s configuration file. Please refer to the Tp-Note’s man-page for details.
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:
Mark Text — a simple and elegant Markdown editor focused on speed and usability.
Typora — a Markdown editor, Markdown reader. Make sure that you have at least version 0.9.89 installed, as this version contains a bugfix required to work properly with Tp-Note.
ReText — Simple but powerful editor for Markdown and reStructuredText
VS-Code, Atom …
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.
Tp-Note’s internal viewer starts automatically the default
browser after the file editor is opened or when invoked with
tp-note --view.
Please refer to Tp-Note’s man-page to learn how to register a file extension with one Tp-Note’s internal markup renderer or to learn how to change the HTML-template that renders the viewer page in the browser.
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.
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!
Make the directory
C:\Windows\tp-note\bin\and movetp-note.exeinto it.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\""
Save the file as:
File name:
tp-note.regSave as type:
All filesEncoding:
UTF-16 LE
Double-click on
tp-note.regand confirm several times.Assign
tp-noteas default application for.md-files
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
Most file-manager allow extending the context menu. As an example, the following images show the configuration of the Thunar-file-manger.
In Thunar’s menu go to:
Edit -> Configure custom actions...
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:
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.
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.
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.
[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.