diff --git a/posts/typst-notes.md b/posts/typst-notes.md new file mode 100644 index 0000000..9bcbbcf --- /dev/null +++ b/posts/typst-notes.md @@ -0,0 +1,219 @@ +# note-taking with typst and neovim + +2023-08-14 + +A while back, I saw Gilles Castel's [series](https://castel.dev/post/lecture-notes-1/) +of blog posts about his note-taking setup with LaTeX and Vim. +I was quite inspired by the idea, and I even tried it for a while, +but gave up in the end. +It was less effort to start writing in a plain text file than to write in LaTeX. +So, these were my goals for a note-taking system: + +- Taking notes should be convenient. + I should be able to to open a new notes page and start writing in a short amount of time. +- The syntax for the notes should be easy to remember. + If I need to look up syntax for common things, I'm wasting time. +- I should be able to put basic math, figures, etc. in my notes. + +Eventually, I found a typesetting system called [Typst](https://github.com/typst/typst). +Typst is kind of a mix between LaTeX and other formats like Markdown. +On one hand, it's designed for working with math and other technical subjects, like LaTeX. +On the other hand, it has a relatively simple syntax reminiscent of Markdown. +Compare these two snippets: + +LaTeX: + +``` +Then, starting from 2: +\begin{enumerate} + \item If the current number is composite, we skip to the next number. + \item Mark all factors of the current number as composite. + \item Move to the next number. +\end{enumerate} +``` + +Typst: + +``` +Then, starting from 2: ++ If the current number is composite, we skip to the next number. ++ Mark all factors of the current number as composite. ++ Move to the next number. +``` + +Because of the above advantages, I decided to start writing things down in Typst. +In this blog post, I'll be documenting my process and tools for Typst note-taking at the time of writing. + +## neovim setup + +Currently, I'm using the [typst.vim](https://github.com/kaarmu/typst.vim) plugin to integrate Typst with Neovim. +It provides basic syntax highlighting, and recognizes `.typ` files as Typst files. +The plugin also has a "watch" command that compiles your Typst file on change to a PDF. +However, I haven't figured out how to have it display compiler errors, so I have this in my Neovim config: + +``` +function TypstWatch() + vsp + vertical resize 20 + exec 'terminal ' .. 'typst watch ' .. expand("%:") + exec "norm \h" +endfunc +nnoremap fc :call TypstWatch() +nnoremap fr :silent exec "!zathura --fork " . expand("%:p:r") . ".pdf &" +``` + +This sets up a bind to open `typst watch` in a terminal pane on the right, +with another bind to open the PDF in Zathura. +Every time I save the content in my text editor, it updates the PDF seamlessly. +It looks like this on screen: + +[ ![](/public/img/typst-notes/nvim-thumb.jpg) ](/public/img/typst-notes/nvim.jpg) + +### templates + +Users of LaTeX or Typst often use templates in order to configure things like document size, layout, fonts, style, and so on. +Instead of redefining these settings every time, we can just import them from a file. +I won't go into detail here; read the relvant Typst [documentation](https://typst.app/docs/tutorial/making-a-template/) for information. +For reference, you can find my own [templates](https://github.com/dogeystamp/typst-templates) at GitHub along with instructions for using them. +The developers of Typst are working on better ways of packaging templates at the moment, so beware that they're not the best example of how to write templates. + +Anyways, you always need to import the templates for every new document you make, +and you also need to pass in parameters like the title of the document. +Typing all this boilerplate manually would be tedious, if done for every document. +This is where [UltiSnips](https://github.com/SirVer/ultisnips) comes in handy. +UltiSnip provides snippets, which are templates of text that you can rapidly paste in the editor. +For example, I've set it up so typing `today` and pressing Tab prints out the current date: + +[ ![](/public/img/typst-notes/today-thumb.gif) ](/public/img/typst-notes/today.gif) + +Snippets also support slots where you can type your own text. +Every time Tab is pressed again, it moves to the next slot instantly. +Here, you can see my snippet for new documents in action: + +[ ![](/public/img/typst-notes/general-thumb.gif) ](/public/img/typst-notes/general.gif) + +With this setup for Neovim, I have achieved the goal of being able to start writing new notes rapidly. +It only takes around twenty seconds to open a new file in the editor, then fill out the template information, +after which I can start writing. + +### version control + +When dealing with any textual content, a good practice is to put it under version control like Git. +This is the norm for code, but it's also viable for LaTeX/Typst content. +The main advantages of this are: + +- You're sure you won't accidentally delete any data, +- You can roll back to older versions, and +- You can easily view what changed between versions. + +For that reason, I set up a private GitHub repo for storing all my notes in a single folder. +Besides that, I also set up the templates as a submodule. +Like this, I can clone the notes repository and also get my templates set up at the same time. + +## math & code + +In the notes I'm writing, I often have to deal with mathematical expressions and code. +You can see [here](https://castel.dev/post/lecture-notes-1/#latex-snippets) +that Castel gets a lot of use out of UltiSnips for rapidly typing math in LaTeX. +However, in Typst, I find that these snippets are mostly unnecessary, +since it has cleaner, simpler syntax for math in general. + +For example, this is the LaTeX syntax for a fraction: + +``` +\frac{3}{2} +``` +Typst has a much more minimal syntax: + +``` +3/2 +``` + +Typst also has a simpler math "environment" syntax. +Anything between dollar signs `$"like this"$` is inline math. +To use display math, add any spacing `$ "like this" $`. +With [auto-pairs](https://github.com/jiangmiao/auto-pairs) for Neovim, +it only takes a single keystroke to start a math expression, +and another to end one. +See it here in action: + +[ ![](/public/img/typst-notes/math-thumb.gif) ](/public/img/typst-notes/math.mp4) + +Another bit of syntax sugar that's built-in to Typst is support for code blocks. +Inline code is introduced by single backticks, +while multi-line code is introduced by triple backticks. +This is _exactly_ the same syntax as in Markdown, which is much more familiar than `\begin{verbatim}`. +It also provides syntax highlighting out of the box, without needing to import lstlisting: + +[ ![](/public/img/typst-notes/code-thumb.gif) ](/public/img/typst-notes/code.mp4) + +## figures + +Being able to draw diagrams in the notes is also a necessary feature. +This part of my setup is mostly unaltered from Castel's own method of drawing figures. +Read his own [blog post](https://castel.dev/post/lecture-notes-2/) regarding drawing figures for the best explanation of how it works. +To briefly summarize his post, Castel uses Inkscape to draw figures, +with a shortcut script that accelerates the process. +He says that he can draw almost as fast as his lecturers draw on the blackboard, +although I'm not nearly skilled enough to do the same. +Here's an example from his blog post: + +[ ![](/public/img/typst-notes/castel-fig-thumb.jpg) ](/public/img/typst-notes/castel-fig.jpg) + +Again, read Castel's blog post about drawing figures. +Here, I will only explain the modifications I made to his process, +assuming you already know how it works. + +So, first of all, Castel's shortcut manager ([GitHub](https://github.com/gillescastel/inkscape-shortcut-manager)) +is quite useful, and does indeed speed up drawing considerably. +However, it's built to deal with LaTeX only, +which is not compatible with my notes. +Therefore, I patched his scripts so that they hook into Typst rather than latexmk. +The results of this are available [on GitHub](https://github.com/dogeystamp/inkscape-shortcut-manager). +Besides that, I also have a snippet for figures in Typst. +It has slots for inputting the filename/ID of the figure, and also a caption for it. +Once the snippet is pasted, I can hover over the filename and press `ff`, +which opens that figure in Inkscape, or creates it if it doesn't exist. +Then, I can draw things, and have it appear in my notes. +Here's a full demo of drawing a figure (click for a non-gif version): + +[ ![](/public/img/typst-notes/figure-thumb.gif) ](/public/img/typst-notes/figure.mp4) + +For now, there's the limitation that there is no equivalent of PDF+LaTeX for Typst. +This means that the font for the document is not synced to the font in the figures themselves. + +## linking/references + +Often, when I'm writing notes for a certain topic, I might want to reference another. +Now, it is possible to use a relative path link to another PDF, +but that doesn't allow for referencing specific pages or sections. +Castel himself solved this problem with [Instant Reference](https://github.com/gillescastel/instant-reference), +which creates links with the `phd://` protocol, which is then handled specially by a script. +However, I decided to make my own [rewrite](https://github.com/dogeystamp/pyinstantref) of the script in Python, in contrast to the original written in JavaScript. +I prefer having my packages managed by the system's package manager, rather than by `npm`. +Python is better in this regard, because Arch Linux packages essential Python packages under `extra/python-.*`. + +I have a bind set up to instantly copy a link to the currently viewed page in the PDF. +For example, here I link to my algorithm notes in a document: + +[ ![](/public/img/typst-notes/reference-thumb.gif) ](/public/img/typst-notes/reference.mp4) + +An extra feature I have compared to Castel's version is referencing specific sections. +This is helpful when you modify notes afterwards and a page number points to different content. +A key bind in my PDF reader triggers a rofi menu where you select one of the sections visible on the current page, +after which you can paste the link to that section seamlessly in your notes. + +# conclusion + +I've been using the above system for taking notes on competitive programming problems +and computer science for a few months. +I think that my goals of having a system for notes that was convenient, easy, and featureful has been accomplished. +Indeed, I haven't had to open up a plain text document for taking notes in quite a while; +everything is in Typst now. + +If you want to see the real configuration files behind all of it, check out my dotfiles [on GitHub](https://github.com/dogeystamp/dots). +The important files are `src/.local/bin/typst-figure`, and `src/.config/nvim/typst.vim`. + +Maybe this post will sway you to check out Typst. +But if it hasn't, look at the example on their [GitHub page](https://github.com/typst/typst). +Hopefully, one day Typst will get wider usage, because it's a great typesetting system. diff --git a/public/img/typst-notes/castel-fig-thumb.jpg b/public/img/typst-notes/castel-fig-thumb.jpg new file mode 100644 index 0000000..76cc5d9 Binary files /dev/null and b/public/img/typst-notes/castel-fig-thumb.jpg differ diff --git a/public/img/typst-notes/castel-fig.jpg b/public/img/typst-notes/castel-fig.jpg new file mode 100644 index 0000000..a1a1d4c Binary files /dev/null and b/public/img/typst-notes/castel-fig.jpg differ diff --git a/public/img/typst-notes/code-thumb.gif b/public/img/typst-notes/code-thumb.gif new file mode 100644 index 0000000..3986731 Binary files /dev/null and b/public/img/typst-notes/code-thumb.gif differ diff --git a/public/img/typst-notes/code.mp4 b/public/img/typst-notes/code.mp4 new file mode 100644 index 0000000..08d55ac Binary files /dev/null and b/public/img/typst-notes/code.mp4 differ diff --git a/public/img/typst-notes/figure-thumb.gif b/public/img/typst-notes/figure-thumb.gif new file mode 100644 index 0000000..e8255ec Binary files /dev/null and b/public/img/typst-notes/figure-thumb.gif differ diff --git a/public/img/typst-notes/figure.mp4 b/public/img/typst-notes/figure.mp4 new file mode 100644 index 0000000..d5cf605 Binary files /dev/null and b/public/img/typst-notes/figure.mp4 differ diff --git a/public/img/typst-notes/general-thumb.gif b/public/img/typst-notes/general-thumb.gif new file mode 100644 index 0000000..913d6a0 Binary files /dev/null and b/public/img/typst-notes/general-thumb.gif differ diff --git a/public/img/typst-notes/general.gif b/public/img/typst-notes/general.gif new file mode 100644 index 0000000..aed4677 Binary files /dev/null and b/public/img/typst-notes/general.gif differ diff --git a/public/img/typst-notes/math-thumb.gif b/public/img/typst-notes/math-thumb.gif new file mode 100644 index 0000000..edb5f22 Binary files /dev/null and b/public/img/typst-notes/math-thumb.gif differ diff --git a/public/img/typst-notes/math.mp4 b/public/img/typst-notes/math.mp4 new file mode 100644 index 0000000..c472d8b Binary files /dev/null and b/public/img/typst-notes/math.mp4 differ diff --git a/public/img/typst-notes/nvim-thumb.jpg b/public/img/typst-notes/nvim-thumb.jpg new file mode 100644 index 0000000..19937c0 Binary files /dev/null and b/public/img/typst-notes/nvim-thumb.jpg differ diff --git a/public/img/typst-notes/nvim.jpg b/public/img/typst-notes/nvim.jpg new file mode 100644 index 0000000..a2944ff Binary files /dev/null and b/public/img/typst-notes/nvim.jpg differ diff --git a/public/img/typst-notes/reference-thumb.gif b/public/img/typst-notes/reference-thumb.gif new file mode 100644 index 0000000..b325e67 Binary files /dev/null and b/public/img/typst-notes/reference-thumb.gif differ diff --git a/public/img/typst-notes/reference.mp4 b/public/img/typst-notes/reference.mp4 new file mode 100644 index 0000000..80fe730 Binary files /dev/null and b/public/img/typst-notes/reference.mp4 differ diff --git a/public/img/typst-notes/today-thumb.gif b/public/img/typst-notes/today-thumb.gif new file mode 100644 index 0000000..4f5c252 Binary files /dev/null and b/public/img/typst-notes/today-thumb.gif differ diff --git a/public/img/typst-notes/today.gif b/public/img/typst-notes/today.gif new file mode 100644 index 0000000..39860d7 Binary files /dev/null and b/public/img/typst-notes/today.gif differ