There are a lot of tasks which are so simple that most programmers think that they can just set out and write their own. One of this is note-taking software. There are a couple products out there, but none are quite perfect. And instead of improving one of the existing ones, it is tempting to just start with their own. In the end, of course, there will be just one additional niche solution that only really works for the programmer but not the next user.
Sometimes there are conflicting requirements. Like you want something that is WYSIWYG or not, should it be in the cloud or private. Yet many other things could be made configurable.
I often take notes when sorting my thoughts. That could be as part of my dissertation, drafting blog posts or comparing products when buying something. And now I am looking for a note-taking software that I can use for my dissertation and in the progress I get a blog post out of that. Guess that checks all the boxes then.
My workflow generally consists of writing structured text and adding screenshots, inline math and code snippets along the way. I will compare a few products that I have tried out for note-taking.
On GitHub one can track issues that feature Markdown. We as a research group use it for code and also our analysis code is there. Instead of using e-mail chains I prefer to use the GitHub Issues also for discussion. So I have abused them for note-taking as well.
Adding images is super easy via drag-and-drop. They get uploaded, assigned some random file name and the Markdown image code is inserted. Also I can add code snippets easily. However, math support is not available.
Discussion intermediate results with my coworkers is really easy this way. But it does not quite fit for things where I work on myself. Or where I want to spare everyone the details. Some of my documents are somewhat write-only, and having everyone else read them is a waste of time.
The only Markdown based note taking application that is packaged for Fedora is Notes-Up. It has Markdown stying and one can insert images via the context menu. They get stored internally and I do not have to worry about it.
I also like the interface and how it is structured into notebooks and pages.
My problem with it is that it stores everything in one opaque SQLite database, including the images. This means that one cannot just simply grab a bit of the content and put it elsewhere. One can export as Markdown, but then the images are just gone. One can export to PDF, but it looks quite ugly, rendered with a sans font. At least the paper format is A4.
Also there is no math support. Taking both things together just rule out scientific note-taking with that program.
The Notable software is proprietary software at zero cost. It used to be open source, but is not any more. It stores everything as Markdown files. One can add attachments, but including an image in the document needs many steps and one always has to include them with the relative path
../attachment/ to make it work.
Then I think that it did not have math support either.
It might have really nice search features and tagging abilities, but I did not look further into it because the way that image attachments is not how I like it.
The notes service provided by Google is nice because I have it everywhere. It is intended for many small notes and not the larger report-style notes that I want to create. I surely can use Markup there, it just never gets rendered.
Markdown files on disk
So what I am doing now is just super simple: Having a bunch of Markdown files on disk. This way I can use whatever editor I like (I'm writing this in Marker), switch editors whenever I feel like it.
Image attachments are not automatic, but I just place the images into the same directory as the Markdown file. And to be able to disentagle different notes from each other I just place each note into a separate directory. As the directory name is the title of the note and there is just one Markdown file per directory, I just call it
index.md. The directory tree simply looks like this:
Notes ├── 20190910-Thermal State Removal │ └── index.md ├── 20200521-cA2.09.48 Stride Investigation │ ├── Bildschirmfoto_20200521-001-11:57RR-Auswahl.png │ ├── Bildschirmfoto_20200521-001-12:01RR-Auswahl.png │ ├── Bildschirmfoto_20200521-008-Auswahl.png │ ├── Bildschirmfoto_20200521-009-Auswahl.png │ ├── Bildschirmfoto_20200521-010-Auswahl.png │ ├── Bildschirmfoto_20200521-011-Auswahl.png │ ├── index.md │ └── pattern-of-three.png └── 20200527-Fit Ranges on cA2.09.48 ├── Bildschirmfoto_20200527-15:01:46-cc5-Auswahl.png └── index.md
- This is the exact same structure that I use with my Nikola blog.
I can search these notes using grep, I can easily take parts and post them on GitHub (having to manually upload the images, though). I can transfer it to my blog without any change. I can use Pandoc to create HTML or PDF representations that use a style of my liking.
So with this I do lack the tagging features that other products have, but I have sufficient flexiblity.
It organizes notes into notebooks and notes, just like Notes-Up does it. There is also support for subnotebooks if one wants to. It features different editor/viewer layouts and looks quite nice.
In the screenshot you can see a note that I have imported from a Markdown file. As one can see it has imported the resources and gave them new file names. Looking at the storage location, one can see how the files are organized internally. There is an SQLite database for the text and just a bunch of image files in a directory for the attachments.
.config/joplin-desktop/ ├── database.sqlite ├── log-database.txt ├── log.txt ├── resources │ ├── 0201cb0e79504a2eb2dbbe86a8c7e03f.png │ ├── 08b9967321044c568ac95a8b97e70162.png │ ├── 1265211db9c44f73af4180b631cadf32.png │ ├── 17ae36ee61374060b3354fdfb23adf84.png │ ├── 3c3bc0f3b07d42a8bc8f7c6baaeabcc8.png │ ├── 4588241bdd6746e5971f18c3b4c2a8a2.png │ ├── 48318c1398d844a29940165c8f56e8ac.png │ ├── 7adbc50b5c8f4e82b987da16b806c569.png │ ├── 91a9a9c8900a43c18b4f84e71e702c75.png │ ├── 949e4a3db15c4f2db1c1c0f8410ae38d.png │ ├── aa311dbb245f42bf884374351ff336ba.png │ ├── d0f78216da644fddb3be67459d86827f.png │ ├── d7e677f076fe43d0b49e2df6463d8ec7.png │ ├── d995468686e547dc9ea86ef7342fc506.png │ └── e596671aeb28483d9facccbe22286623.png └── tmp ├── 0490ff23787f12db22752281cf1e783c.css ├── 0e0bbcc8bdd6f998d40e7713def8228a.css ├── 5969ba3480f4296debea17c0689daf5f.css ├── a7043796e0413c96d5f16aa3394553ac.css └── c6446da69e9e26701d8d96aac114a41b.css
One can then export this as Markdown again and obtains the following structure.
/tmp/export-test/ ├── Promotion │ ├── cA2.09.48 Stride Investigation.md │ ├── Fit Ranges on cA2.09.48.md │ └── Thermal State Removal for Three Pions.md └── _resources ├── 0201cb0e79504a2eb2dbbe86a8c7e03f.png ├── 08b9967321044c568ac95a8b97e70162.png ├── 17ae36ee61374060b3354fdfb23adf84.png ├── 3c3bc0f3b07d42a8bc8f7c6baaeabcc8.png ├── 4588241bdd6746e5971f18c3b4c2a8a2.png ├── 48318c1398d844a29940165c8f56e8ac.png ├── 7adbc50b5c8f4e82b987da16b806c569.png ├── 91a9a9c8900a43c18b4f84e71e702c75.png ├── 949e4a3db15c4f2db1c1c0f8410ae38d.png ├── aa311dbb245f42bf884374351ff336ba.png ├── d7e677f076fe43d0b49e2df6463d8ec7.png └── d995468686e547dc9ea86ef7342fc506.png
This is something that one can work with, although the matching between the resources and the documents is not directly clear. This makes sense as a resource could be used in multiple documents and therefore this approach makes more sense if the notes are interpreted in a collected fashion. But one can also export just a single document and then the
_resources directory only contains the ones that have been used. Otherwise one could parse the Markdown documents for the filenames that are included in image tags and take them from the resources directory.
PDF generation is not as nice as with Pandoc via LaTeX, but using the export to Markdown feature one could also generate the PDF via Pandoc. The image files compatible with HTML (JPEG, PNG) also properly show up, but PDF images do not show up in either editor or PDF export. To be fair, PDF images also do not work with GitHub Issues or every other Markdown editor. It just works with Pandoc export to LaTeX.
The math support is not full LaTeX. I sometimes use environments like
multline which are not Markdown constructs but rather LaTeX that is passed through as-is when I compile the Markdown to LaTeX using Pandoc.
Joplin vs. Files
I have a really hard time deciding whether I want to use Joplin or plain Markdown files for my notes. The integrated nature of Joplin makes it rather easy to have a repository of notes. Also I can just drag-and-drop my screenshot into the editor and have them automatically managed in the background, like GitHub Issues also does. This is more manual work with plain files.
However, the UNIX philosophy of having everything represented as plain text files also has its appeal. I can switch editors, track the notes individually in my backup snapshots, track them in git and collaborate on a single note. Joplin does support multiple note directories, but it encourages to keep a bunch of notes together in a notebook and possibly multiple notebooks in one directory. I would likely have all my dissertation notes in one thing.
There are certain long-lived documents like my diary. I don't want to submit that to some program which stores the data in a non-standard format. But my dissertation notes only have a half-life of a few weeks to months. Also they are not final documents, they are just notes. I thought that if I was using plain Markdown files for some of the documents, I could just use them for all my Markdown stuff.
The big issue is that I have little projects and they have some notes here and there. It does not make so much sense to have all the notes concentrated in one notebook and other files around elsewhere. I like to have all the project files in one directory. Therefore I think that I will stick with plain Markdown files for my notes and don't have to worry about them turning into fully fledged documents.