Markup languages like Markdown, ReStructuredText, asciidoc, textile, txt2tags or mediawiki are perfectly suited for fast note taking. Type your notes with your favorite editor, chose your favorite markup language1 and view them with Chromium, Chrome or Firefox2.

All you need is this pandoc-note script, the Pandoc format converter, an editor of your choice and Chromium, Chrome or Firefox as live previewer. If not available, pandoc-note also works without pandoc.

pandoc-note runs under Linux and Windows. The script operates in four modes depending on it’s options (see Invoking pandoc-note):

Create a new note

Edit notes

View notes

Sync filename

The project is hosted on Github: getreu/pandoc-notetaking. The project’s webpage is on http://blog.getreu.net. There you also find a pdf rendition of this document.

Read more about the 2 most common use cases in Section How students take notes.

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 I am concerned I am not good at logistics. For me having all documents and notes in one little machine is a blessing.

To illustrate how to work with pandoc-note here my most common workflows.

1.1 The lesson starts

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 you want to create a new note in and right-click on some empty white space.

The new file

The new file

Editor and Browser windows with unmodified template

Editor and Browser windows with unmodified template

Title change

Title change

Some text added

Some text added

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 pandoc-note renames the file to be in sync with the document's metadata, i.e. title, subtitle and file-extension. For more details see Document title - filename sync

1.2 Taking notes about a file

We want to take a note about a pdf

We want to take a note about a pdf

Editor and Browser windows with unmodified template

Editor and Browser windows with unmodified template

We add a note about the origin of the pdf

We add a note about the origin of the pdf

The new note file on disk after closing the editor

The new note file on disk after closing the editor

2 Quickstart

pandoc-note can be easily configured for your personal preferences and needs3. This section explains a basic standard setup to get you started quickly. The default setup runs under Linux and uses leafpad as editor and firefox as viewer.

2.1 Install dependencies

  1. Install the following packages:

      apt-get install pandoc inotify-tools leafpad firefox
  2. Install the auto-reload plugin in Firefox.

  3. Get and install the pandoc-note-binary:

      cd /usr/local/bin
      sudo wget https://raw.githubusercontent.com/getreu/pandoc-notetaking/master/bin/pandoc-note
      sudo chown a+x pandoc-note

2.2 Run pandoc-note

On a shell type:

    pandoc-note

or:

    pandoc-note <file-to-annotate>

2.3 Optional personalization

Read Section Linux or Section Windows for a personalized setup.

Read Linux file manager configuration.

3 Create a new note

There are several ways to launch pandoc-note.

Linux
Windows

3.1 Invoking pandoc-note

 pandoc-note --help
 pandoc-note -h

shows a short help text with available command line options:

/usr/local/bin/pandoc-note creates, edits or views a note with markups.

usage:

   /usr/local/bin/pandoc-note [-h][-v|-e|-s] | [<Textfile>.<Ext>|<File>|<Dir>]

<Dir>|<File>: directory where the new note file will be created
(current directory if none).
If a binary <File> is given a new note file will be created next
to <FILE>.
A given <Textfile> is opened and edited. <Ext> determines
the markup-language such as Markdown, ReStructuredText, MediaWiki
and others.
Filename of <File> is changed when not in sync with the file's
metadata YAML block.

Options:

--view,
-v  Do not open editor, open viewer only.

--edit,
-e  Do not open viewer, only new note or, sync filename and edit.

--sync,
-s  Do not open editor or viewer, only new note or sync filename.

--help,
-h  Show this message.
pandoc-note options
Option Create a new note Launch editor Launch viewer Sync title-filen ame

without

Y *

Y

Y

Y

-v, --view

Y *

N

Y

N

-e, --edit

Y *

Y

N

Y

-s, --sync

Y *

N

N

Y

Lengend:

Y = yes
N = no
* = If a note with the same filename exists on disk already, no new note is created.

3.2 Directory as parameter

3.2.1 Syntax

 pandoc-note <path>/<dir>

creates the following document:

<path>/<dir>/YYYYMMDD-<dir>--Notes.md
---
title:    '<dir>'
subtitle: ''
author:   <login name>
date:     <current date>
revision: 1.0
fileext:  md
---

3.2.2 Example

 pandoc-note 'doc/Lecture 1'

creates the following document:

doc/Lecture 1/20170809-Lecture 1--Notes.md
---
title:    'Lecture 1'
subtitle: 'Notes'
author:   getreu
date:     2017-08-09
revision: 1.1
fileext:  md
---

3.3 No parameter

3.3.1 Syntax

It is also possible to invoke the script without options:

 pandoc-note

The result is the same as above but the current working directory is used for <path>/<dir>.

3.3.2 Example

 cd 'doc/Lecture 1'
 pandoc-note

creates the following document:

doc/Lecture 1/20170809-Lecture 1--Notes.md
---
title:    'Lecture 1'
subtitle: 'Notes'
author:   getreu
date:     2017-08-09
revision: 1.0
fileext:  md
---

3.4 Filename as parameter

The filename should be some existing local file you want to annotate. For example I use this feature to note from where I have downloaded a .pdf.

3.4.1 Syntax

When invoke with a filename, no date stamp is prepended.

 pandoc-note <path>/<dir>/<filename>.<ext>

The new file will be created here:

<path>/<dir>/<filename>.<ext>--Notes.md

And it will look like this:

---
title:    '<filename>.<ext>'
subtitle: 'Notes'
author:   <login name>
date:     <current date>
revision: 1.0
fileext:  md
---

Annotations on [file](<path>/<dir>/<filename>.<ext>)

3.4.2 Example

 pandoc-note 'doc/Implementing the NIST Cybersecurity Framework.pdf'

creates the following document

doc/Implementing the NIST Cybersecurity Framework.pdf--Notes.md

with the content:

---
title:    'Implementing the NIST Cybersecurity Framework.pdf'
subtitle: 'Notes'
author:   getreu
date:     2017-08-09
revision: 1.0
fileext:  md
---

Annotations on [file](Implementing the NIST Cybersecurity Framework.pdf)

Before quitting the pandoc-note script executes it’s editing-mode. This opens in your editor the completed template (see example above) and a live-previewer showing the rendered text file:

example filename

example filename

4 Editing notes

4.1 Syntax

  pandoc-note <path>/<filename>.md

launches the the gvim editor by default. Replace gvim by any editor of your choice. At the same time a chrome or chromium window will pop up showing the live rendition of your markdown file.

You may want to use some autosave editor feature in order to observe changes immediately in the rendered preview live.

Before opening the editor and after closing it, pandoc-note calls the internal function SyncFilename. It guarantees that any change in the YAML header of the file you have been editing will replicate in the filename of that markdown file. This guarantees that the filenames of markdown notes always correspond to their metadata allowing you to find your notes quickly in your directory structure. See Document title - filename sync for more details.

4.2 Example

  pandoc-note 'Implementing the NIST Cybersecurity Framework.pdf--Notes.md'

The same result is obtained by repeating the same command you used to create this note 4:

  pandoc-note 'Implementing the NIST Cybersecurity Framework.pdf'

5 Viewing notes

5.1 Syntax

  pandoc-note --view <path>/<filename>.<ext>
  pandoc-note -v <path>/<filename>.<ext>

launches your preferred viewer: firefox or chromium5.

5.2 Example

  pandoc-note -v 'Implementing the NIST Cybersecurity Framework.pdf--Notes.md'
view invokation example

view invokation example

All text in the above example was automatically generated by the pandoc-note script only the last link Download pdf was added “by hand”. This is particularly useful for quickly writing down the source of a downloaded document.

6 Document title - filename sync

Consider the following note file:

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

The filename has 4 parts:

<order mark>-<simplified-title>--<simplified-subtitle>.<ext>

A <order mark> can be a

<order mark> can be any combination of 0123456789-_.

When pandoc-note creates a new note based on a directory it prepends a chronological order mark of today. The <simplified-title> part is derived from the parent directory name omitting its own order mark.

filing system: sequence number order mark

filing system: sequence number order mark

  pandoc-note '10-Mein Körper'

will result in a new file:

filing system: chronological order mark

filing system: chronological order mark

10-Mein Körper/20151209-Mein Körper--Notes.md

Note

The parent directory’s order mark is never used to compose a filename for a new note.

When pandoc-note creates a new note based on a filename no order mark is prepended.

Before and after editing the pandoc-note analyses the title, subtitle and fileext of the YAML header of the markdown file and simplifies them in a filesystem friendly form. If the result does not equal to <simplified-title>--<simplified-subtitle>.<ext> the filename is changed on disk. Possible order marks remain untouched.

Important

pandoc-note might change the note’s filename but never changes an order mark!

For details about how the metadata is simplified into a <simplified-title>--<simplified-subtitle> string refer to the SanitizeFilename() function in [src/pandoc-note].

7 Personalized installation and configuration

pandoc-note runs on Linux and Windows. For Windows installation and configuration see Windows below.

This Section tries to cover many setup variants and maybe confusing to beginners. If you just want to get started quickly go to the Quickstart section for a standard setup.

7.1 Choose your favorite markup language

7.1.1 Set the default markup language for new notes

The default markup language for new notes is Markdown. To change the default modify the DEFAULT_EXT variable in the ### CONFIGURATION SECTION of pandoc-note, e.g. DEFAULT_EXT="rst" sets the default for new notes to ReStructuredText. Valid values are: md, markdown, mkd, rst, rest, txt, t2t, textile, twiki and mediawiki (cf. Markups variable in pandoc-note).

7.1.2 Change the markup language for an existing note

pandoc-note determines the markup language by the note's filename extension. For example md means that the note is formatted in Markdown. Like the filename itself, the filename extension is kept in sync with the document's YAML metadata header (see Section Document title - filename sync). To change the markup language for a given note change the value of the fileext variable in the header to a filename extension Pandoc recognizes as input file. Valid values are: md, markdown, mkd, rst, rest, txt, t2t, textile, twiki and mediawiki (cf. Markups variable in pandoc-note). For example: in order to switch the markup language from Markdown to ReStructuredText, change fileext: md to fileext: rst. Be sure to save the note, close the editor, close the viewer and reopen the note for changes to take effect. Doing so will change the note's filename extension from md to rst.

Warning

Do not change the filename extension manually, as the change will be reverted next time you open the note with pandoc-note. Instead, change the fileext variable in the note's header.

7.2 Choose your favorite editor and favorite viewer

7.2.1 Editor

The editor must be an Unicode text editor. Under Linux every editor will do. Make sure that your editor does not "fork", meaning that it must block the invoking shell as long as your are editing. This is the only way for pandoc-note to know when you finished editing. Most editors work this way, some like vim can be invoked with vim --no-fork to achieve this behaviour.

Do not use Notepad under Windows as it does not support Unicode. Use Wordpad instead.

Configuration Linux

Edit in the pandoc-note the LaunchEditor() function. Uncomment one choice only.

Configuration Windows

Edit the file pandoc-note.bat and uncomment one example only.

7.2.2 Live Previewer

The viewer of your choice implies a choice on how you will render markdown into html. You can choose among the following:

  1. Render with Pandoc and view with Firefox (recommended)

    For this work you need to install the following:

    sudo apt-get install pandoc inotify-tools

    In Firefox install the auto-reload plugin from here.

    This is my preferred solution because you are free to use any markup language Pandoc supports, e.g. ReStructuredText, Textile, MediaWiki and many others.

    Currently this solution works only under Linux because it relies on the inotify-tools package with is not available in BusyBox.

  2. Render and wiew with Firefox

    In Firefox install the markdown-viewer-webext plugin from here.

    The new MIME-type has to be registered in Firefox. This blog explains how.

    Optionally you can install viewer plugins for other markup languages you want to use, such as Asciidoctor.js Live Preview.

  3. Render and view with Chrome or Chromium[^5]

    Install the following package

     sudo apt-get install uni2ascii

    [section pending]

  4. Do no use a browser as previewer but use the editor's build-in previewer instead

    Some editors have a build-in previewer like ReText. For the Atom-editor plug-ins for Markdown, Asciidoc, and ReStructuredText are available.

Configuration Linux

Edit in the pandoc-note the LaunchViewer() function. Uncomment one choice only.

Configuration Windows

Edit the file pandoc-note.bat and uncomment one example only.

7.3 Linux

  1. Install an Editor and a Live previewer of your choice (see above).

  2. Download the note-taking-script bin/pandoc-note from Github getreu/pandoc-notetaking. Alternatively you can copy and paste the listing at end of this document.

  3. Copy it in a location of your $PATH and make it executable for everyone.

      sudo cp pandoc-note /usr/local/bin
      sudo chmod a+rx /usr/local/bin/pandoc-note
  4. Configuration:

    At the beginning of pandoc-note you will find a section enclosed in the commments CONFIGURATION SECTION START and CONFIGURATION SECTION END.

    Here you can specify what editor you want to use, if you choose firefox, chrome or chromium and you can specify the parameters these programs require. Make sure that your editor does not fork when launched. If it does fork, the script will still work but when you quit, no title-filename synchronization will occur. Outside the CONFIGURATION SECTION no changes should be necessary.

    Warning

    The environment variables PANDOC_EDITOR or PANDOC_VIEWER -when set- have precedence over settings in the CONFIGURATION SECTION and will override them.

    See the Section Editor and the Section Live previewer for details.

  5. Test the installation: open a console window and type pandoc-note. An editor and viewer window containing a note template should open.

  6. Optional: integrate the scripts with your file-manager (see Linux file manager configuration).

7.4 Windows

  1. Install an Editor and a Live previewer of your choice (see above).

  2. Download the the files bin/pandoc-note, bin/pandoc-note.bat and bin/busybox.exe from Github getreu/markdown-notetaking. Alternatively you can copy and paste the listings at end of this document. The version of busybox in the above repository is outdated. Download the BusyBox executable busybox.exe.

  3. Copy the 3 files in a directory of your choice. In the following I call this directory BIN_DIR.

  4. Configuration:

    At the beginning of pandoc-note.bak you will find a section enclosed in the commments CONFIGURATION SECTION START and CONFIGURATION SECTION END.

    Note

    The only file you edit to change the default choices for editor and viewer under Windows is adco-note.bat. Not pandoc-note!

    Important

    New notes are created with an Unicode BOM indicating Unicode encoding. Do not use the notepad editor as it does not understand Unicode. Use Wordpad or any other modern Unicode editor instead.

    Here you can specify what browser you want to use, e.g. if you choose firefox.exe or chromium.exe and you can specify the parameters these programs require. Do the same for the editor of your choice. Make sure that your editor does not fork when launched. If it does fork, the script will still work but when you quit, no title-filename synchronization will occur. Outside the CONFIGURATION SECTION no changes should be necessary.

    See the Section Editor and the Section Live previewer for details.

  5. Create a shortcut to pandoc-note.bat on your desktop, click on properties and change the shortcut to run minimized. Let the start in path empty.

    shortcut properties

    shortcut properties

  6. Test the installation: drag a file or directory on the pandoc-note Shortcut on your desktop. An editor and viewer window should open.

  7. Optional: integrate the scripts with your file-manager (see Windows file explorer configuration).

7.5 Integration with file manager

This section shows how to integrate pandoc-note with your file manager.

7.5.1 Linux file manager configuration

The example below shows the Thunar filebrowser’s custom actions.

Integration with file-manager

Integration with file-manager

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

Thunar custom action configuration

Thunar custom action configuration

Edit custom action

Edit custom action

Appearance Condition

Appearance Condition

7.5.2 Windows file explorer configuration

  1. Open a folder containing an .md file.

  2. Right-click the .md file and point to Open with and then click Choose default program.

    Choose default program...

    Choose default program...

  3. Select the Always use the selected program and then click Browse…​.

    Browse to...

    Browse to...

  4. Click Browse…​ then browse to your BIN_DIR directory, select pandoc-note.bak and click Open and later Ok.

    Browse to pandoc-note

    Browse to pandoc-note

Further reading:


  1. pandoc-note supports all Pandoc's plain text input formats (see: pandoc --list-input-formats). pandoc-note guesses the markup language from the file extension of the text file. Currently md, markdown, mkd, rst, rest, txt, t2t, textile, twiki and mediawiki are supported.

  2. As alternative editors with build-in previewer are supported.

  3. For a personalized setup read the installation guide for Linux or Windows.

  4. This only works if you have not changed the original title of the note file in the meantime!

  5. pandoc-note can be also configured not to use a viewer when your editor has a build in markdown-viewer. In this case -v is ignored.