typstar 1.5.0__tar.gz

typstar-1.5.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.3
+Name: typstar
+Version: 1.5.0
+Summary: Neovim plugin for efficient note taking in Typst
+Author: arne314
+Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: appdirs>=1.4.4
+Requires-Dist: tree-sitter==0.25.2
+Requires-Dist: tree-sitter-typst
+Requires-Dist: typer>=0.24.1
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Python: >=3.11.10
+Description-Content-Type: text/markdown
+
+# Typstar
+Neovim plugin for efficient (mathematical) note taking in Typst
+
+See changes in [`CHANGELOG.md`](./CHANGELOG.md)
+
+[![Weekly Integration](https://github.com/arne314/typstar/actions/workflows/weekly.yml/badge.svg)](https://github.com/arne314/typstar/actions/workflows/weekly.yml)
+
+## Features
+- Powerful autosnippets using [LuaSnip](https://github.com/L3MON4D3/LuaSnip/) and [Tree-sitter](https://tree-sitter.github.io/) (inspired by [fastex.nvim](https://github.com/lentilus/fastex.nvim))
+- Easy insertion of drawings using [Obsidian Excalidraw](https://github.com/zsviczian/obsidian-excalidraw-plugin) or [Rnote](https://github.com/flxzt/rnote)
+- Export of [Anki](https://apps.ankiweb.net/) flashcards \[No Neovim required\]
+
+## Usage
+
+### Snippets
+Use `:TypstarToggleSnippets` to toggle all snippets at any time.
+To efficiently navigate insert nodes and avoid overlapping ones,
+use `:TypstarSmartJump` and `:TypstarSmartJumpBack`.
+Available snippets can mostly be intuitively derived from [here](././lua/typstar/snippets), they include:
+
+Universal snippets:
+- Alphanumeric characters: `:<char>` &#8594; `$<char>$ ` in markup (e.g. `:X` &#8594; `$X$ `, `:5` &#8594; `$5$ `)
+- Greek letters: `;<latin>` &#8594; `<greek>` in math and `$<greek>$ ` in markup (e.g. `;a` &#8594; `alpha`/`$alpha$ `)
+- Common indices (numbers and letters `i-n`): `<letter><index> ` &#8594; `<letter>_<index> ` in math and `$<letter>$ <index> ` &#8594; `$<letter>_<index>$ ` in markup (e.g `A314 ` &#8594; `A_314 `, `$alpha$ n ` &#8594; `$alpha_n$ `, `$F$ n,` &#8594; `$F_n$, `, `$F$ n.` &#8594; `$F_n$.`)
+- Primes: `$<letter>$ ' ` &#8594; `$<letter>'$ ` and in combination with index and punctuation like above (e.g. `$phi$ ' ` &#8594; `$phi'$ `, `$phi$ 5'` &#8594; `$phi'_5$ `, `$f$ '5.` &#8594; `$f'_5$.`, `f'5,` &#8594; `f'_5, `)
+
+You can find a complete map of latin to greek letters including reasons for the less intuitive ones [here](./lua/typstar/snippets/letters.lua).
+Note that some greek letters have multiple latin ones mapped to them.
+
+Markup snippets:
+- Begin inline math with `kk` and multiline math with `dm`
+- [Markup shorthands](./lua/typstar/snippets/markup.lua) (e.g. `HIG` &#8594; `#highlight[<cursor>]`, `IMP` &#8594; `$==>$ `)
+- [ctheorems shorthands](./lua/typstar/snippets/markup.lua) (e.g. `tem` &#8594; empty theorem, `exa` &#8594; empty example)
+- [Flashcards](#anki): `fla` and `flA`
+- All above snippets support visual mode via the [selection key](#installation)
+
+Math snippets:
+- [Many shorthands](./lua/typstar/snippets/math.lua) for mathematical expressions
+- Series of numbered letters: `<letter> <z/o>t<optional last index> ` &#8594; `<letter>_<0/1>, <letter>_<1/2>, ... ` (e.g. `a ot ` &#8594; `a_1, a_2, ... `, `a zt4 ` &#8594; `a_0, a_1, a_2, a_3, a_4 `, `alpha otk ` &#8594; `alpha_1, alpha_2, ..., alpha_k `, `oti ` &#8594; `1, 2, ..., i `)
+- Wrapping of any mathematical expression (see [operations](./lua/typstar/snippets/visual.lua), works nested, multiline and in visual mode via the [selection key](#installation)): `<expression><operation>` &#8594; `<operation>(<expression>)` (e.g. `(a^2+b^2)rt` &#8594; `sqrt(a^2+b^2)`, `lambdatd` &#8594; `tilde(lambda)`, `(1+1)sQ` &#8594; `[1+1]`, `(1+1)sq` &#8594; `[(1+1)]`)
+- Simple functions: `fo<value> ` &#8594; `f(<value>) ` (e.g. `fox ` &#8594; `f(x) `, `ao5 ` &#8594; `a(5) `)
+- Matrices: `<size>ma` and `<size>lma` (e.g. `23ma` &#8594; 2x3 matrix)
+
+Note that you can [customize](#custom-snippets) (enable, disable and modify) every snippet.
+
+### Excalidraw/Rnote
+- Use `:TypstarInsertExcalidraw`/`:TypstarInsertRnote` to
+  create a new drawing using the [configured](#configuration) template,
+  insert a figure displaying it and open it in Obsidian/Rnote.
+- To open an inserted drawing in Obsidian/Rnote,
+  simply run `:TypstarOpenDrawing` (or `:TypstarOpenExcalidraw`/`:TypstarOpenRnote` if you are using the same file extension for both)
+  while your cursor is on a line referencing the drawing.
+
+### Anki
+Use the `flA` snippet to create a new flashcard
+```typst
+#flashcard(0, "My first flashcard")[
+  Typst is awesome $a^2+b^2=c^2$
+]
+```
+or the `fla` snippet to add a more complex front
+```typst
+#flashcard(0)[I love Typst $pi$][
+  This is the back of my second flashcard
+]
+```
+
+To render the flashcard in your document as well add some code like this
+```typst
+#let flashcard(id, front, back) = {
+  strong(front)
+  [\ ]
+  back
+}
+```
+
+- Add a comment like `// ANKI: MY::DECK` to your document to set a deck used for all flashcards after this comment (You can use multiple decks per file)
+- Add a file named `.anki` containing a deck name to define a default deck on a directory base
+- Add a file named `.anki.typ` to define a preamble on a directory base. You can find the default preamble [here](./src/anki/typst_compiler.py).
+- Tip: Despite the use of SVGs you can still search your flashcards in Anki as the typst source is added into an invisible html paragraph
+
+#### Neovim
+- Use `:TypstarAnkiScan` to scan the current nvim working directory and compile all flashcards in its context, unchanged files will be ignored
+- Use `:TypstarAnkiForce` to force compilation of all flashcards in the current working directory even if the files haven't changed since the last scan (e.g. on preamble change)
+- Use `:TypstarAnkiForceCurrent` to force compilation of all flashcards in the file currently edited
+- Use `:TypstarAnkiReimport` to also add flashcards that have already been assigned an id but are not currently
+present in Anki
+- Use `:TypstarAnkiForceReimport` and `:TypstarAnkiForceCurrentReimport` to combine features accordingly
+
+#### Standalone
+- Run `typstar-anki --help` to show the available options
+
+
+## Installation
+Install the plugin in Neovim and run the plugin setup.
+You can install and run a demo installation using [Nix](#in-a-nix-flake-optional)).
+```lua
+require('typstar').setup({ -- depending on your neovim plugin system
+   -- your typstar config goes here
+})
+```
+
+<details>
+<summary>Example lazy.nvim config</summary>
+
+```lua
+{
+    "arne314/typstar",
+    dependencies = {
+        "L3MON4D3/LuaSnip",
+    },
+    ft = { "typst" },
+    keys = {
+        {
+            "<M-t>",
+            "<Cmd>TypstarToggleSnippets<CR>",
+            mode = { "n", "i" },
+        },
+        {
+            "<M-j>",
+            "<Cmd>TypstarSmartJump<CR>",
+            mode = { "s", "i" },
+        },
+        {
+            "<M-k>",
+            "<Cmd>TypstarSmartJumpBack<CR>",
+            mode = { "s", "i" },
+        },
+    },
+    config = function()
+        local typstar = require("typstar")
+        typstar.setup({
+            -- your typstar configuration
+            add_undo_breakpoints = true,
+        })
+    end,
+},
+{
+    "L3MON4D3/LuaSnip",
+    version = "v2.*",
+    build = "make install_jsregexp",
+    config = function()
+        local luasnip = require("luasnip")
+        luasnip.config.setup({
+            enable_autosnippets = true,
+            cut_selection_keys = "<Tab>",
+        })
+    end,
+},
+{
+    "nvim-treesitter/nvim-treesitter",
+    build = ":TSUpdate",
+    branch = "main",
+    lazy = false,
+    config = function()
+        require('nvim-treesitter').install { "typst" }
+    end
+},
+```
+</details>
+
+### Snippets
+0. The snippets are designed to work with Typst `0.14`. For older versions check out the legacy `typst-0.13` branch.
+1. Install [LuaSnip](https://github.com/L3MON4D3/LuaSnip/), set `enable_autosnippets = true` and set a visual mode selection key (e.g. `cut_selection_keys = '<Tab>'`) in the configuration
+2. Install [jsregexp](https://github.com/kmarius/jsregexp) as described [here](https://github.com/L3MON4D3/LuaSnip/blob/master/DOC.md#transformations) (You will see a warning on startup if jsregexp isn't installed properly)
+3. Install [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) and run `:TSInstall typst`
+4. Make sure you haven't remapped `<C-g>`. Otherwise set `add_undo_breakpoints = false` in the [config](#configuration)
+5. Optional: Setup [ctheorems](https://typst.app/universe/package/ctheorems/) with names like [here](./lua/typstar/snippets/markup.lua)
+
+### Excalidraw
+1. Install [Obsidian](https://obsidian.md/) and create a vault in your typst note taking directory
+2. Install the [obsidian-excalidraw-plugin](https://github.com/zsviczian/obsidian-excalidraw-plugin) and enable `Auto-export SVG` (in plugin settings at `Embedding Excalidraw into your Notes and Exporting > Export Settings > Auto-export Settings`)
+3. Have the `xdg-open` command working or set a different command at `uriOpenCommand` in the [config](#configuration)
+4. If you encounter issues with the file creation of drawings, try cloning the repo into `~/typstar` or setting the `typstarRoot` config accordingly; feel free to open an issue
+
+### Rnote
+1. Install [Rnote](https://github.com/flxzt/rnote?tab=readme-ov-file#installation); I recommend not using flatpak as that might cause issues with file permissions.
+2. Make sure `rnote-cli` is available in your `PATH` or set a different command at `exportCommand` in the [config](#configuration)
+3. Have the `xdg-open` command working with Rnote files or set a different command at `uriOpenCommand` in the [config](#configuration)
+4. See comment 4 above at Excalidraw
+
+### Anki
+1. Install [Anki](https://apps.ankiweb.net/#download)
+2. Install [Anki-Connect](https://ankiweb.net/shared/info/2055492159) and make sure `http://localhost` is added to `webCorsOriginList` in the Add-on config (should be added by default)
+3. Install the typstar python package (I recommend using [uv](https://docs.astral.sh/uv/) via `uv tool install git+https://github.com/arne314/typstar`, you will need to have python build tools and clang installed) \[Note: this may take a while\]
+4. Make sure the `typstar-anki` command is available in your `PATH` or modify the `typstarAnkiCmd` option in the [config](#configuration)
+
+### In a Nix Flake (optional)
+To try a minimal demo setup, run `nix run github:arne314/typstar#nvim -- test.typ` (200MB download).
+The keybindings are defined [here](./lua/tests/basic_init.lua)
+
+You can add typstar to your `nix-flake` like so
+```nix
+# `flake.nix`
+inputs = {
+  # ... other inputs
+  typstar = {
+    url = "github:arne314/typstar";
+    flake = false;
+  };
+}
+```
+Now you can use `typstar` in any package-set
+```nix
+with pkgs; [
+  # ... other packages
+  (pkgs.vimUtils.buildVimPlugin {
+     name = "typstar";
+     src = inputs.typstar; 
+     buildInputs = with pkgs.vimPlugins; [
+        luasnip
+        nvim-treesitter-parsers.typst
+     ];
+  })
+]
+```
+
+## Configuration
+Configuration options can be intuitively derived from the table [here](./lua/typstar/config.lua).
+
+### Excalidraw/Rnote templates
+The `templatePath` option expects a table that maps file patterns to template locations.
+To for example have a specific template for lectures, you could configure it like this
+```Lua
+templatePath = {
+    { 'lectures/.*%.excalidraw%.md$', '~/Templates/lecture_excalidraw.excalidraw.md' }, -- path contains "lectures"
+    { '%.excalidraw%.md$', '~/Templates/default_excalidraw.excalidraw.md' }, -- fallback
+},
+```
+
+### Custom snippets
+The [config](#configuration) allows you to
+- disable all snippets via `snippets.enable = false`
+- only include specific modules from the snippets folder via e.g. `snippets.modules = { 'letters' }`
+- exclude specific triggers via e.g. `snippets.exclude = { 'dx', 'ddx' }`
+- disable different behaviors of snippets from the `visual` module
+    - visual selection via e.g. `snippets.visual_disable = { 'br' }`
+    - normal snippets (`abs` &#8594; `abs(1+1)`) via e.g. `snippets.visual_disable_normal = { 'abs' }`
+    - postfix snippets (`xabs` &#8594; `abs(x)`) via e.g. `snippets.visual_disable_postfix = { 'abs' }`
+
+For further customization you can make use of the provided wrappers from within your [LuaSnip](https://github.com/L3MON4D3/LuaSnip/) config.
+Let's say you prefer the short `=>` arrow over the long `==>` one and would like to change the `ip` trigger to `imp`.
+Your `typstar` config could look like
+```lua
+require('typstar').setup({
+    snippets = {
+        exclude = { 'ip' },
+    },
+})
+```
+while your LuaSnip `typst.lua` could look like this (`<` and `>` require escaping as `<>` [introduces a new node](https://github.com/L3MON4D3/LuaSnip/blob/master/DOC.md#fmt))
+```lua
+local tp = require('typstar.autosnippets')
+local snip = tp.snip
+local math = tp.in_math
+local markup = tp.in_markup
+
+return {
+    -- add a new snippet (the old one is excluded via the config)
+    snip('imp', '=>> ', {}, math),
+
+    -- override existing triggers by setting a high priority
+    snip('ib', '<<= ', {}, math, 2000),
+    snip('iff', '<<=>> ', {}, math, 2000),
+
+    -- setup markup snippets accordingly
+    snip('IMP', '$=>>$ ', {}, markup, 2000),
+    snip('IFF', '$<<=>>$ ', {}, markup, 2000),
+}
+```
+
+## Contribution
+Feel free to open an issue or a PR.
+
+For development, a nix shell is provided, which you can enter via `nix develop`.
+Running `nvim` from within the shell will launch a minimal installation of the plugin, sourced at startup, so no additional nix build is needed.
+Tests can be executed using `just test` from within the shell or via `nix flake check`.
+The code can be linted using `just lint`.
+Run `just --list` for more details.
+

typstar-1.5.0/README.md

@@ -0,0 +1,280 @@
+# Typstar
+Neovim plugin for efficient (mathematical) note taking in Typst
+
+See changes in [`CHANGELOG.md`](./CHANGELOG.md)
+
+[![Weekly Integration](https://github.com/arne314/typstar/actions/workflows/weekly.yml/badge.svg)](https://github.com/arne314/typstar/actions/workflows/weekly.yml)
+
+## Features
+- Powerful autosnippets using [LuaSnip](https://github.com/L3MON4D3/LuaSnip/) and [Tree-sitter](https://tree-sitter.github.io/) (inspired by [fastex.nvim](https://github.com/lentilus/fastex.nvim))
+- Easy insertion of drawings using [Obsidian Excalidraw](https://github.com/zsviczian/obsidian-excalidraw-plugin) or [Rnote](https://github.com/flxzt/rnote)
+- Export of [Anki](https://apps.ankiweb.net/) flashcards \[No Neovim required\]
+
+## Usage
+
+### Snippets
+Use `:TypstarToggleSnippets` to toggle all snippets at any time.
+To efficiently navigate insert nodes and avoid overlapping ones,
+use `:TypstarSmartJump` and `:TypstarSmartJumpBack`.
+Available snippets can mostly be intuitively derived from [here](././lua/typstar/snippets), they include:
+
+Universal snippets:
+- Alphanumeric characters: `:<char>` &#8594; `$<char>$ ` in markup (e.g. `:X` &#8594; `$X$ `, `:5` &#8594; `$5$ `)
+- Greek letters: `;<latin>` &#8594; `<greek>` in math and `$<greek>$ ` in markup (e.g. `;a` &#8594; `alpha`/`$alpha$ `)
+- Common indices (numbers and letters `i-n`): `<letter><index> ` &#8594; `<letter>_<index> ` in math and `$<letter>$ <index> ` &#8594; `$<letter>_<index>$ ` in markup (e.g `A314 ` &#8594; `A_314 `, `$alpha$ n ` &#8594; `$alpha_n$ `, `$F$ n,` &#8594; `$F_n$, `, `$F$ n.` &#8594; `$F_n$.`)
+- Primes: `$<letter>$ ' ` &#8594; `$<letter>'$ ` and in combination with index and punctuation like above (e.g. `$phi$ ' ` &#8594; `$phi'$ `, `$phi$ 5'` &#8594; `$phi'_5$ `, `$f$ '5.` &#8594; `$f'_5$.`, `f'5,` &#8594; `f'_5, `)
+
+You can find a complete map of latin to greek letters including reasons for the less intuitive ones [here](./lua/typstar/snippets/letters.lua).
+Note that some greek letters have multiple latin ones mapped to them.
+
+Markup snippets:
+- Begin inline math with `kk` and multiline math with `dm`
+- [Markup shorthands](./lua/typstar/snippets/markup.lua) (e.g. `HIG` &#8594; `#highlight[<cursor>]`, `IMP` &#8594; `$==>$ `)
+- [ctheorems shorthands](./lua/typstar/snippets/markup.lua) (e.g. `tem` &#8594; empty theorem, `exa` &#8594; empty example)
+- [Flashcards](#anki): `fla` and `flA`
+- All above snippets support visual mode via the [selection key](#installation)
+
+Math snippets:
+- [Many shorthands](./lua/typstar/snippets/math.lua) for mathematical expressions
+- Series of numbered letters: `<letter> <z/o>t<optional last index> ` &#8594; `<letter>_<0/1>, <letter>_<1/2>, ... ` (e.g. `a ot ` &#8594; `a_1, a_2, ... `, `a zt4 ` &#8594; `a_0, a_1, a_2, a_3, a_4 `, `alpha otk ` &#8594; `alpha_1, alpha_2, ..., alpha_k `, `oti ` &#8594; `1, 2, ..., i `)
+- Wrapping of any mathematical expression (see [operations](./lua/typstar/snippets/visual.lua), works nested, multiline and in visual mode via the [selection key](#installation)): `<expression><operation>` &#8594; `<operation>(<expression>)` (e.g. `(a^2+b^2)rt` &#8594; `sqrt(a^2+b^2)`, `lambdatd` &#8594; `tilde(lambda)`, `(1+1)sQ` &#8594; `[1+1]`, `(1+1)sq` &#8594; `[(1+1)]`)
+- Simple functions: `fo<value> ` &#8594; `f(<value>) ` (e.g. `fox ` &#8594; `f(x) `, `ao5 ` &#8594; `a(5) `)
+- Matrices: `<size>ma` and `<size>lma` (e.g. `23ma` &#8594; 2x3 matrix)
+
+Note that you can [customize](#custom-snippets) (enable, disable and modify) every snippet.
+
+### Excalidraw/Rnote
+- Use `:TypstarInsertExcalidraw`/`:TypstarInsertRnote` to
+  create a new drawing using the [configured](#configuration) template,
+  insert a figure displaying it and open it in Obsidian/Rnote.
+- To open an inserted drawing in Obsidian/Rnote,
+  simply run `:TypstarOpenDrawing` (or `:TypstarOpenExcalidraw`/`:TypstarOpenRnote` if you are using the same file extension for both)
+  while your cursor is on a line referencing the drawing.
+
+### Anki
+Use the `flA` snippet to create a new flashcard
+```typst
+#flashcard(0, "My first flashcard")[
+  Typst is awesome $a^2+b^2=c^2$
+]
+```
+or the `fla` snippet to add a more complex front
+```typst
+#flashcard(0)[I love Typst $pi$][
+  This is the back of my second flashcard
+]
+```
+
+To render the flashcard in your document as well add some code like this
+```typst
+#let flashcard(id, front, back) = {
+  strong(front)
+  [\ ]
+  back
+}
+```
+
+- Add a comment like `// ANKI: MY::DECK` to your document to set a deck used for all flashcards after this comment (You can use multiple decks per file)
+- Add a file named `.anki` containing a deck name to define a default deck on a directory base
+- Add a file named `.anki.typ` to define a preamble on a directory base. You can find the default preamble [here](./src/anki/typst_compiler.py).
+- Tip: Despite the use of SVGs you can still search your flashcards in Anki as the typst source is added into an invisible html paragraph
+
+#### Neovim
+- Use `:TypstarAnkiScan` to scan the current nvim working directory and compile all flashcards in its context, unchanged files will be ignored
+- Use `:TypstarAnkiForce` to force compilation of all flashcards in the current working directory even if the files haven't changed since the last scan (e.g. on preamble change)
+- Use `:TypstarAnkiForceCurrent` to force compilation of all flashcards in the file currently edited
+- Use `:TypstarAnkiReimport` to also add flashcards that have already been assigned an id but are not currently
+present in Anki
+- Use `:TypstarAnkiForceReimport` and `:TypstarAnkiForceCurrentReimport` to combine features accordingly
+
+#### Standalone
+- Run `typstar-anki --help` to show the available options
+
+
+## Installation
+Install the plugin in Neovim and run the plugin setup.
+You can install and run a demo installation using [Nix](#in-a-nix-flake-optional)).
+```lua
+require('typstar').setup({ -- depending on your neovim plugin system
+   -- your typstar config goes here
+})
+```
+
+<details>
+<summary>Example lazy.nvim config</summary>
+
+```lua
+{
+    "arne314/typstar",
+    dependencies = {
+        "L3MON4D3/LuaSnip",
+    },
+    ft = { "typst" },
+    keys = {
+        {
+            "<M-t>",
+            "<Cmd>TypstarToggleSnippets<CR>",
+            mode = { "n", "i" },
+        },
+        {
+            "<M-j>",
+            "<Cmd>TypstarSmartJump<CR>",
+            mode = { "s", "i" },
+        },
+        {
+            "<M-k>",
+            "<Cmd>TypstarSmartJumpBack<CR>",
+            mode = { "s", "i" },
+        },
+    },
+    config = function()
+        local typstar = require("typstar")
+        typstar.setup({
+            -- your typstar configuration
+            add_undo_breakpoints = true,
+        })
+    end,
+},
+{
+    "L3MON4D3/LuaSnip",
+    version = "v2.*",
+    build = "make install_jsregexp",
+    config = function()
+        local luasnip = require("luasnip")
+        luasnip.config.setup({
+            enable_autosnippets = true,
+            cut_selection_keys = "<Tab>",
+        })
+    end,
+},
+{
+    "nvim-treesitter/nvim-treesitter",
+    build = ":TSUpdate",
+    branch = "main",
+    lazy = false,
+    config = function()
+        require('nvim-treesitter').install { "typst" }
+    end
+},
+```
+</details>
+
+### Snippets
+0. The snippets are designed to work with Typst `0.14`. For older versions check out the legacy `typst-0.13` branch.
+1. Install [LuaSnip](https://github.com/L3MON4D3/LuaSnip/), set `enable_autosnippets = true` and set a visual mode selection key (e.g. `cut_selection_keys = '<Tab>'`) in the configuration
+2. Install [jsregexp](https://github.com/kmarius/jsregexp) as described [here](https://github.com/L3MON4D3/LuaSnip/blob/master/DOC.md#transformations) (You will see a warning on startup if jsregexp isn't installed properly)
+3. Install [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) and run `:TSInstall typst`
+4. Make sure you haven't remapped `<C-g>`. Otherwise set `add_undo_breakpoints = false` in the [config](#configuration)
+5. Optional: Setup [ctheorems](https://typst.app/universe/package/ctheorems/) with names like [here](./lua/typstar/snippets/markup.lua)
+
+### Excalidraw
+1. Install [Obsidian](https://obsidian.md/) and create a vault in your typst note taking directory
+2. Install the [obsidian-excalidraw-plugin](https://github.com/zsviczian/obsidian-excalidraw-plugin) and enable `Auto-export SVG` (in plugin settings at `Embedding Excalidraw into your Notes and Exporting > Export Settings > Auto-export Settings`)
+3. Have the `xdg-open` command working or set a different command at `uriOpenCommand` in the [config](#configuration)
+4. If you encounter issues with the file creation of drawings, try cloning the repo into `~/typstar` or setting the `typstarRoot` config accordingly; feel free to open an issue
+
+### Rnote
+1. Install [Rnote](https://github.com/flxzt/rnote?tab=readme-ov-file#installation); I recommend not using flatpak as that might cause issues with file permissions.
+2. Make sure `rnote-cli` is available in your `PATH` or set a different command at `exportCommand` in the [config](#configuration)
+3. Have the `xdg-open` command working with Rnote files or set a different command at `uriOpenCommand` in the [config](#configuration)
+4. See comment 4 above at Excalidraw
+
+### Anki
+1. Install [Anki](https://apps.ankiweb.net/#download)
+2. Install [Anki-Connect](https://ankiweb.net/shared/info/2055492159) and make sure `http://localhost` is added to `webCorsOriginList` in the Add-on config (should be added by default)
+3. Install the typstar python package (I recommend using [uv](https://docs.astral.sh/uv/) via `uv tool install git+https://github.com/arne314/typstar`, you will need to have python build tools and clang installed) \[Note: this may take a while\]
+4. Make sure the `typstar-anki` command is available in your `PATH` or modify the `typstarAnkiCmd` option in the [config](#configuration)
+
+### In a Nix Flake (optional)
+To try a minimal demo setup, run `nix run github:arne314/typstar#nvim -- test.typ` (200MB download).
+The keybindings are defined [here](./lua/tests/basic_init.lua)
+
+You can add typstar to your `nix-flake` like so
+```nix
+# `flake.nix`
+inputs = {
+  # ... other inputs
+  typstar = {
+    url = "github:arne314/typstar";
+    flake = false;
+  };
+}
+```
+Now you can use `typstar` in any package-set
+```nix
+with pkgs; [
+  # ... other packages
+  (pkgs.vimUtils.buildVimPlugin {
+     name = "typstar";
+     src = inputs.typstar; 
+     buildInputs = with pkgs.vimPlugins; [
+        luasnip
+        nvim-treesitter-parsers.typst
+     ];
+  })
+]
+```
+
+## Configuration
+Configuration options can be intuitively derived from the table [here](./lua/typstar/config.lua).
+
+### Excalidraw/Rnote templates
+The `templatePath` option expects a table that maps file patterns to template locations.
+To for example have a specific template for lectures, you could configure it like this
+```Lua
+templatePath = {
+    { 'lectures/.*%.excalidraw%.md$', '~/Templates/lecture_excalidraw.excalidraw.md' }, -- path contains "lectures"
+    { '%.excalidraw%.md$', '~/Templates/default_excalidraw.excalidraw.md' }, -- fallback
+},
+```
+
+### Custom snippets
+The [config](#configuration) allows you to
+- disable all snippets via `snippets.enable = false`
+- only include specific modules from the snippets folder via e.g. `snippets.modules = { 'letters' }`
+- exclude specific triggers via e.g. `snippets.exclude = { 'dx', 'ddx' }`
+- disable different behaviors of snippets from the `visual` module
+    - visual selection via e.g. `snippets.visual_disable = { 'br' }`
+    - normal snippets (`abs` &#8594; `abs(1+1)`) via e.g. `snippets.visual_disable_normal = { 'abs' }`
+    - postfix snippets (`xabs` &#8594; `abs(x)`) via e.g. `snippets.visual_disable_postfix = { 'abs' }`
+
+For further customization you can make use of the provided wrappers from within your [LuaSnip](https://github.com/L3MON4D3/LuaSnip/) config.
+Let's say you prefer the short `=>` arrow over the long `==>` one and would like to change the `ip` trigger to `imp`.
+Your `typstar` config could look like
+```lua
+require('typstar').setup({
+    snippets = {
+        exclude = { 'ip' },
+    },
+})
+```
+while your LuaSnip `typst.lua` could look like this (`<` and `>` require escaping as `<>` [introduces a new node](https://github.com/L3MON4D3/LuaSnip/blob/master/DOC.md#fmt))
+```lua
+local tp = require('typstar.autosnippets')
+local snip = tp.snip
+local math = tp.in_math
+local markup = tp.in_markup
+
+return {
+    -- add a new snippet (the old one is excluded via the config)
+    snip('imp', '=>> ', {}, math),
+
+    -- override existing triggers by setting a high priority
+    snip('ib', '<<= ', {}, math, 2000),
+    snip('iff', '<<=>> ', {}, math, 2000),
+
+    -- setup markup snippets accordingly
+    snip('IMP', '$=>>$ ', {}, markup, 2000),
+    snip('IFF', '$<<=>>$ ', {}, markup, 2000),
+}
+```
+
+## Contribution
+Feel free to open an issue or a PR.
+
+For development, a nix shell is provided, which you can enter via `nix develop`.
+Running `nvim` from within the shell will launch a minimal installation of the plugin, sourced at startup, so no additional nix build is needed.
+Tests can be executed using `just test` from within the shell or via `nix flake check`.
+The code can be linted using `just lint`.
+Run `just --list` for more details.
+

typstar-1.5.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "typstar"
+version = "1.5.0"
+description = "Neovim plugin for efficient note taking in Typst"
+authors = [
+    { name = "arne314" }
+]
+readme = "README.md"
+requires-python = ">=3.11.10"
+dependencies = [
+    "aiohttp>=3.13.3",
+    "appdirs>=1.4.4",
+    "tree-sitter==0.25.2",
+    "tree-sitter-typst",
+    "typer>=0.24.1",
+    "typing-extensions>=4.15.0",
+]
+
+[project.scripts]
+typstar-anki = "anki.main:main"
+
+[tool.ruff]
+lint.extend-select = ["I"]
+line-length = 100
+
+[dependency-groups]
+dev = [
+    "ruff>=0.8.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "anki"
+
+[tool.uv.workspace]
+members = [
+    "vendor/tree_sitter_typst",
+]
+
+[tool.uv.sources]
+tree-sitter-typst = { workspace = true }
+

typstar-1.5.0/src/anki/anki_api.py

@@ -0,0 +1,152 @@
+import asyncio
+import base64
+from collections import defaultdict
+from typing import Iterable, List
+
+import aiohttp
+
+from .flashcard import Flashcard
+
+
+async def gather_exceptions(coroutines):
+    for result in await asyncio.gather(*coroutines, return_exceptions=True):
+        if isinstance(result, Exception):
+            raise result
+
+
+class AnkiConnectError(Exception):
+    pass
+
+
+class AnkiConnectApi:
+    url: str
+    api_key: str
+    semaphore: asyncio.Semaphore
+
+    def __init__(self, url: str, api_key: str):
+        self.url = url
+        self.api_key = api_key
+        self.semaphore = asyncio.Semaphore(2)  # increase in case Anki implements multithreading
+
+    async def push_flashcards(self, cards: Iterable[Flashcard], reimport: bool):
+        add: dict[str, List[Flashcard]] = defaultdict(list)
+        update: dict[str, List[Flashcard]] = defaultdict(list)
+        n_add: int = 0
+        n_update: int = 0
+
+        for card in cards:
+            if card.is_new():
+                add[card.deck].append(card)
+                n_add += 1
+            else:
+                update[card.deck].append(card)
+                n_update += 1
+        if reimport:
+            reimport_cards = await self._check_reimport(update)
+            print(f"Found {len(reimport_cards)} flashcards to reimport")
+            for card in reimport_cards:
+                update[card.deck].remove(card)
+                add[card.deck].append(card)
+                n_update -= 1
+                n_add += 1
+
+        print(
+            f"Pushing {n_add} new flashcards and {n_update} updated flashcards to Anki...",
+            flush=True,
+        )
+        await self._create_required_decks({*add.keys(), *update.keys()})
+        await self._add_new_cards(add)
+        await gather_exceptions(
+            [
+                *self._update_cards_requests(add),
+                *self._update_cards_requests(update, True),
+            ]
+        )
+
+    async def _request_api(self, action, **params):
+        async with aiohttp.ClientSession() as session:
+            data = {
+                "action": action,
+                "key": self.api_key,
+                "params": params,
+                "version": 6,
+            }
+            try:
+                async with self.semaphore:
+                    async with session.post(url=self.url, json=data) as response:
+                        result = await response.json(encoding="utf-8")
+                        if err := result["error"]:
+                            raise AnkiConnectError(err)
+                        return result["result"]
+            except aiohttp.ClientError as e:
+                raise AnkiConnectError(f"Could not connect to Anki: {e}")
+
+    async def _update_note_model(self, card: Flashcard):
+        await self._request_api("updateNoteModel", note=card.as_anki_model())
+
+    async def _store_media(self, card):
+        await self._request_api(
+            "storeMediaFile",
+            filename=card.svg_filename(True),
+            data=base64.b64encode(card.svg_front).decode(),
+        )
+        await self._request_api(
+            "storeMediaFile",
+            filename=card.svg_filename(False),
+            data=base64.b64encode(card.svg_back).decode(),
+        )
+
+    async def _change_deck(self, deck: str, cards: List[int]):
+        await self._request_api("changeDeck", deck=deck, cards=cards)
+
+    async def _add_new_cards(self, cards_map: dict[str, List[Flashcard]]):
+        notes: List[Flashcard] = []
+        notes_data: List[dict] = []
+        for cards in cards_map.values():
+            for card in cards:
+                data = {
+                    "deckName": card.deck,
+                    "options": {
+                        "allowDuplicate": True,  # won't work with svgs
+                    },
+                }
+                data.update(card.as_anki_model(True))
+                notes.append(card)
+                notes_data.append(data)
+        result = await self._request_api("addNotes", notes=notes_data)
+        for idx, note_id in enumerate(result):
+            notes[idx].update_id(note_id)
+
+    async def _create_required_decks(self, required: Iterable[str]):
+        existing = await self._request_api("deckNamesAndIds")
+        requests = []
+        for deck in required:
+            if deck not in existing:
+                requests.append(self._request_api("createDeck", deck=deck))
+        await gather_exceptions(requests)
+
+    async def _check_reimport(self, cards_map: dict[str, List[Flashcard]]) -> List[Flashcard]:
+        cards = []
+        for cs in cards_map.values():
+            cards.extend(cs)
+        if not cards:
+            return []
+        existing = await self._request_api(
+            "findNotes", query=f"nid:{','.join([str(c.note_id) for c in cards])}"
+        )
+        return [c for c in cards if c.note_id not in existing]
+
+    def _update_cards_requests(
+        self, cards_map: dict[str, List[Flashcard]], update_deck: bool = True
+    ):
+        requests = []
+        for deck, cards in cards_map.items():
+            card_ids = []
+            for card in cards:
+                requests.append(self._update_note_model(card))
+                requests.append(self._store_media(card))
+                if update_deck:
+                    card_ids.append(card.note_id)
+            if card_ids:
+                requests.append(self._change_deck(deck, card_ids))
+        return requests

typstar-1.5.0/src/anki/config_parser.py

@@ -0,0 +1,39 @@
+from collections import defaultdict
+from functools import cache
+from glob import glob
+from pathlib import Path
+
+
+class RecursiveConfigParser:
+    dir: Path
+    targets: set[str]
+    results: dict[str, dict[Path, str]]
+
+    def __init__(self, dir, targets, recursive=True):
+        self.dir = dir
+        self.targets = set(targets)
+        self.results = defaultdict(dict)
+        self._parse_dirs(recursive)
+
+    def _parse_dirs(self, recursive=True):
+        files = []
+        for target in self.targets:
+            if recursive:
+                dir = f"{self.dir}/**/{target}"
+            else:
+                dir = f"{self.dir}/{target}"
+            files.extend(glob(dir, include_hidden=target.startswith("."), recursive=recursive))
+        for file in files:
+            file = Path(file)
+            if file.name in self.targets:
+                self.results[file.name][file.parent] = file.read_text(encoding="utf-8")
+
+    @cache
+    def get_config(self, path: Path, target) -> str | None:
+        root_parent = self.dir.parent.resolve()
+        path = Path(path.resolve())
+        target_results = self.results[target]
+        while path != root_parent:
+            if result := target_results.get(path):
+                return result
+            path = path.parent

typstar-1.5.0/src/anki/file_handler.py

@@ -0,0 +1,56 @@
+import hashlib
+from pathlib import Path
+from typing import List
+
+import tree_sitter
+
+
+class FileHandler:
+    file_path: Path
+    file_content: List[bytes]
+
+    def __init__(self, path: Path):
+        self.file_path = path
+        self.read()
+
+    @property
+    def directory_path(self) -> Path:
+        return self.file_path.parent
+
+    def get_bytes(self) -> bytes:
+        return b"".join(self.file_content)
+
+    def get_file_hash(self) -> str:
+        return hashlib.md5(self.get_bytes(), usedforsecurity=False).hexdigest()
+
+    def get_node_content(self, node: tree_sitter.Node, remove_outer=False) -> str:
+        content = (
+            b"".join(self.file_content[node.start_point.row : node.end_point.row + 1])[
+                node.start_point.column : -(
+                    len(self.file_content[node.end_point.row]) - node.end_point.column
+                )
+            ]
+        ).decode()
+        return content[1:-1] if remove_outer else content
+
+    def update_node_content(self, node: tree_sitter.Node, value):
+        new_lines = self.file_content[: node.start_point.row]
+        first_line = self.file_content[node.start_point.row][: node.start_point.column]
+        last_line = self.file_content[node.end_point.row][node.end_point.column :]
+        new_lines.extend(
+            (
+                line + b"\n"
+                for line in (first_line + str(value).encode() + last_line).split(b"\n")
+                if line != b""
+            )
+        )
+        new_lines.extend(self.file_content[node.end_point.row + 1 :])
+        self.file_content = new_lines
+
+    def read(self):
+        with self.file_path.open("rb") as f:
+            self.file_content = f.readlines()
+
+    def write(self):
+        with self.file_path.open("wb") as f:
+            f.writelines(self.file_content)

typstar-1.5.0/src/anki/flashcard.py

@@ -0,0 +1,92 @@
+import html
+
+import tree_sitter
+
+from .file_handler import FileHandler
+
+
+class Flashcard:
+    note_id: int
+    front: str
+    back: str
+    deck: str
+    id_updated: bool
+
+    preamble: str | None
+    file_handler: FileHandler
+
+    note_id_node: tree_sitter.Node
+    front_node: tree_sitter.Node
+    back_node: tree_sitter.Node
+
+    svg_front: bytes
+    svg_back: bytes
+
+    def __init__(
+        self,
+        front: str,
+        back: str,
+        deck: str | None,
+        note_id: int,
+        preamble: str | None,
+        file_handler: FileHandler,
+    ):
+        if deck is None:
+            deck = "Default"
+        if not note_id:
+            note_id = 0
+        self.front = front
+        self.back = back
+        self.deck = deck
+        self.note_id = note_id
+        self.preamble = preamble
+        self.file_handler = file_handler
+        self.id_updated = False
+
+    def __str__(self):
+        return f"Flashcard(id={self.note_id}, front={self.front})"
+
+    def as_typst(self, front: bool) -> str:
+        return f"#flashcard({self.note_id})[{self.front if front else ''}][{self.back if not front else ''}]"
+
+    def as_html(self, front: bool) -> str:
+        safe_front = html.escape(self.front)
+        safe_back = html.escape(self.back)
+        prefix = f"<p hidden>{safe_front}: {safe_back}{' ' * 10}</p>"  # indexable via anki search
+        image = f'<img src="{self.svg_filename(front)}" />'
+        return prefix + image
+
+    def as_anki_model(self, tmp: bool = False) -> dict:
+        model = {
+            "modelName": "Basic",
+            "fields": {
+                "Front": f"tmp typst: {self.front}" if tmp else self.as_html(True),
+                "Back": f"tmp typst: {self.back}" if tmp else self.as_html(False),
+            },
+            "tags": ["typst"],
+        }
+        if not self.is_new():
+            model["id"] = self.note_id
+        return model
+
+    def svg_filename(self, front: bool) -> str:
+        return f"typst_{self.note_id}_{'front' if front else 'back'}.svg"
+
+    def is_new(self) -> bool:
+        return self.note_id == 0 or self.note_id is None
+
+    def set_ts_nodes(
+        self, front: tree_sitter.Node, back: tree_sitter.Node, note_id: tree_sitter.Node
+    ):
+        self.front_node = front
+        self.back_node = back
+        self.note_id_node = note_id
+
+    def update_id(self, value: int):
+        if self.note_id != value:
+            self.note_id = value
+            self.id_updated = True
+
+    def set_svgs(self, front, back):
+        self.svg_front = front
+        self.svg_back = back

typstar-1.5.0/src/anki/main.py

@@ -0,0 +1,87 @@
+import asyncio
+import os
+from pathlib import Path
+
+import typer
+from typing_extensions import Annotated
+
+from anki.anki_api import AnkiConnectApi
+from anki.parser import FlashcardParser
+from anki.typst_compiler import TypstCompiler
+
+cli = typer.Typer(name="typstar-anki")
+
+
+async def export_flashcards(
+    root_dir, force_scan, clear_cache, reimport, typst_cmd, anki_url, anki_key
+):
+    parser = FlashcardParser()
+    compiler = TypstCompiler(root_dir, typst_cmd)
+    api = AnkiConnectApi(anki_url, anki_key)
+
+    # parse flashcards
+    if clear_cache:
+        parser.clear_file_hashes()
+    flashcards = parser.parse_directory(root_dir, force_scan)
+
+    # async typst compilation
+    await compiler.compile_flashcards(flashcards)
+
+    try:
+        # async anki push
+        await api.push_flashcards(flashcards, reimport)
+    finally:
+        # write id updates to files
+        parser.update_ids_in_source()
+    parser.save_file_hashes()
+    print("Done", flush=True)
+
+
+@cli.command()
+def cmd(
+    root_dir: Annotated[
+        Path,
+        typer.Option(
+            help="Directory scanned for flashcards and passed over to typst compile command"
+        ),
+    ] = Path(os.getcwd()),
+    force_scan: Annotated[
+        Path | None,
+        typer.Option(
+            help="File/directory to scan for flashcards while ignoring stored "
+            "file hashes (e.g. on preamble change)"
+        ),
+    ] = None,
+    clear_cache: Annotated[
+        bool,
+        typer.Option(
+            help="Clear all stored file hashes (more aggressive than force-scan "
+            "as it clears hashes regardless of their path)"
+        ),
+    ] = False,
+    reimport: Annotated[
+        bool,
+        typer.Option(
+            help="Instead of throwing an error, also add flashcards that have already been assigned an id "
+            "but are not present in Anki. The assigned id will be updated in the source code."
+        ),
+    ] = False,
+    typst_cmd: Annotated[
+        str, typer.Option(help="Typst command used for flashcard compilation")
+    ] = "typst",
+    anki_url: Annotated[str, typer.Option(help="Url for Anki-Connect")] = "http://127.0.0.1:8765",
+    anki_key: Annotated[str | None, typer.Option(help="Api key for Anki-Connect")] = None,
+):
+    asyncio.run(
+        export_flashcards(
+            root_dir, force_scan, clear_cache, reimport, typst_cmd, anki_url, anki_key
+        )
+    )
+
+
+def main():
+    typer.run(cmd)
+
+
+if __name__ == "__main__":
+    main()

typstar-1.5.0/src/anki/parser.py

@@ -0,0 +1,180 @@
+import json
+import re
+from glob import glob
+from pathlib import Path
+from typing import List, Tuple
+
+import appdirs
+from tree_sitter import Language, Parser, Query, QueryCursor
+from tree_sitter_typst import language as get_typst_language
+
+from .config_parser import RecursiveConfigParser
+from .file_handler import FileHandler
+from .flashcard import Flashcard
+
+ts_flashcard_query = """
+(call 
+  item: [
+    (call 
+      item: (call 
+        item: (ident) @fncall
+        (group 
+          (number) @id))
+      (content) @front)
+    (call
+      item: (ident) @fncall
+      (group
+        (number) @id
+        (string) @front))
+    ]
+    (#eq? @fncall "flashcard")
+  ((content) @back
+) @flashcard)
+"""
+
+ts_deck_query = """
+((comment) @deck)
+"""
+deck_regex = re.compile(r"\W+ANKI:\s*([\S ]*)")
+
+
+class FlashcardParser:
+    typst_language: Language
+    typst_parser: Parser
+    flashcard_query_cursor: QueryCursor
+    deck_query_cursor: QueryCursor
+
+    file_handlers: List[tuple[FileHandler, List[Flashcard]]]
+    file_hashes: dict[str, str]
+    file_hashes_store_path: Path = Path(appdirs.user_state_dir("typstar") + "/file_hashes.json")
+
+    def __init__(self):
+        self.typst_language = Language(get_typst_language())
+        self.typst_parser = Parser(self.typst_language)
+        self.flashcard_query_cursor = QueryCursor(Query(self.typst_language, ts_flashcard_query))
+        self.deck_query_cursor = QueryCursor(Query(self.typst_language, ts_deck_query))
+        self.file_handlers = []
+        self._load_file_hashes()
+
+    def _parse_file(
+        self, file: FileHandler, preamble: str | None, default_deck: str | None
+    ) -> List[Flashcard]:
+        cards = []
+        tree = self.typst_parser.parse(file.get_bytes(), encoding="utf8")
+        card_captures = self.flashcard_query_cursor.captures(tree.root_node)
+        if not card_captures:
+            return cards
+        deck_captures = self.deck_query_cursor.captures(tree.root_node)
+
+        def row_compare(node):
+            return node.start_point.row
+
+        card_captures["id"].sort(key=row_compare)
+        card_captures["front"].sort(key=row_compare)
+        card_captures["back"].sort(key=row_compare)
+
+        deck_refs: List[Tuple[int, str | None]] = []
+        deck_refs_idx = -1
+        current_deck = default_deck
+        if deck_captures:
+            deck_captures["deck"].sort(key=row_compare)
+            for comment in deck_captures["deck"]:
+                if match := deck_regex.match(file.get_node_content(comment)):
+                    deck_refs.append(
+                        (
+                            comment.start_point.row,
+                            None if match[1].isspace() else match[1],
+                        )
+                    )
+
+        for note_id, front, back in zip(
+            card_captures["id"], card_captures["front"], card_captures["back"]
+        ):
+            while (
+                deck_refs_idx < len(deck_refs) - 1
+                and back.end_point.row >= deck_refs[deck_refs_idx + 1][0]
+            ):
+                deck_refs_idx += 1
+                current_deck = deck_refs[deck_refs_idx][1]
+
+            card = Flashcard(
+                file.get_node_content(front, True),
+                file.get_node_content(back, True),
+                current_deck,
+                int(file.get_node_content(note_id)),
+                preamble,
+                file,
+            )
+            card.set_ts_nodes(front, back, note_id)
+            cards.append(card)
+        return cards
+
+    def parse_directory(self, root_dir: Path, force_scan: Path | None = None):
+        flashcards = []
+        single_file = None
+        is_force_scan = force_scan is not None
+        if is_force_scan:
+            if force_scan.is_file():
+                single_file = force_scan
+                scan_dir = force_scan.parent
+            else:
+                scan_dir = force_scan
+        else:
+            scan_dir = root_dir
+
+        print(
+            f"Parsing flashcards in {scan_dir if single_file is None else single_file} ...",
+            flush=True,
+        )
+        configs = RecursiveConfigParser(
+            root_dir, {".anki", ".anki.typ"}, recursive=single_file is None
+        )
+
+        for file in glob(f"{scan_dir}/**/**.typ", recursive=True):
+            file = Path(file)
+            if single_file is not None and file != single_file:
+                continue
+
+            fh = FileHandler(file)
+            file_changed = self._hash_changed(fh)
+            if is_force_scan or file_changed:
+                cards = self._parse_file(
+                    fh, configs.get_config(file, ".anki.typ"), configs.get_config(file, ".anki")
+                )
+                self.file_handlers.append((fh, cards))
+                flashcards.extend(cards)
+        return flashcards
+
+    def _hash_changed(self, file: FileHandler) -> bool:
+        file_hash = file.get_file_hash()
+        cached = self.file_hashes.get(str(file.file_path))
+        self.file_hashes[str(file.file_path)] = file_hash
+        return file_hash != cached
+
+    def _load_file_hashes(self):
+        self.file_hashes_store_path.parent.mkdir(parents=True, exist_ok=True)
+        self.file_hashes_store_path.touch()
+        content = self.file_hashes_store_path.read_text()
+        if content:
+            self.file_hashes = json.loads(content)
+        else:
+            self.file_hashes = {}
+
+    def save_file_hashes(self):
+        self.file_hashes_store_path.write_text(json.dumps(self.file_hashes))
+
+    def clear_file_hashes(self):
+        self.file_hashes = {}
+        self.save_file_hashes()
+
+    def update_ids_in_source(self):
+        print("Updating ids in source...", flush=True)
+        for fh, cards in self.file_handlers:
+            file_updated = False
+            for c in cards:
+                if c.id_updated:
+                    fh.update_node_content(c.note_id_node, c.note_id)
+                    file_updated = True
+            if file_updated:
+                fh.write()
+                self.file_hashes[str(fh.file_path)] = fh.get_file_hash()

typstar-1.5.0/src/anki/typst_compiler.py

@@ -0,0 +1,90 @@
+import asyncio
+import os
+import random
+import re
+import sys
+from pathlib import Path
+from typing import List
+
+from .flashcard import Flashcard
+
+default_preamble = """
+#set text(size: 20pt)
+#set page(width: auto, height: auto, margin: (rest: 8pt))
+#let flashcard(id, front, back) = {
+  strong(front)
+  [\\ ]
+  back
+}
+"""
+
+
+class TypstCompilationError(ValueError):
+    regex = re.compile(r"\nerror: ")
+
+
+class TypstCompiler:
+    preamble: str
+    typst_cmd: str
+    typst_root_dir: Path
+    max_processes: int
+
+    def __init__(self, typst_root_dir: Path, typst_cmd: str):
+        self.typst_cmd = typst_cmd
+        self.typst_root_dir = typst_root_dir
+        n_cpus = os.cpu_count()
+        if n_cpus is None:
+            self.max_processes = 10
+        else:
+            self.max_processes = round(1.5 * n_cpus)
+
+    async def _compile(self, src: str, directory: Path) -> bytes:
+        tmp_path = f"{directory}/tmp_{random.randint(1, 1000000000)}.typ"
+        with open(tmp_path, "w", encoding="utf-8") as f:
+            f.write(src)
+        proc = await asyncio.create_subprocess_exec(
+            self.typst_cmd,
+            "compile",
+            tmp_path,
+            "-",
+            "--root",
+            str(self.typst_root_dir),
+            "--format",
+            "svg",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await proc.communicate()
+        os.remove(tmp_path)
+        if stderr:
+            err = bytes.decode(stderr, encoding="utf-8")
+            if TypstCompilationError.regex.search("\n" + err):
+                raise TypstCompilationError(err)
+            else:
+                print(f"Typst compilation warning:\n{err}", file=sys.stderr, flush=True)
+        return stdout
+
+    async def _compile_flashcard(self, card: Flashcard):
+        preamble = default_preamble if card.preamble is None else card.preamble
+        front = await self._compile(
+            preamble + "\n" + card.as_typst(True), card.file_handler.directory_path
+        )
+        back = await self._compile(
+            preamble + "\n" + card.as_typst(False), card.file_handler.directory_path
+        )
+        card.set_svgs(front, back)
+
+    async def compile_flashcards(self, cards: List[Flashcard]):
+        print(f"Compiling {len(cards)} flashcards...", flush=True)
+        semaphore = asyncio.Semaphore(self.max_processes)
+
+        async def compile_coro(card):
+            async with semaphore:
+                return await self._compile_flashcard(card)
+
+        results = await asyncio.gather(
+            *(compile_coro(card) for card in cards), return_exceptions=True
+        )
+        for result in results:
+            if isinstance(result, Exception):
+                raise result