typst-notes.nvim

Typst-centric note-taking and project utilities for Neovim. Modular, async, and built to be lightweight.

This plugin provides a suite of tools to make working with Typst files in Neovim seamless, with a focus on academic and daily note-taking workflows.

---

Features

• Smart PDF Viewer: Automatically opens the compiled PDF when you edit a .typ file and closes it when you're done. The PDF viewer is fully configurable.
• Structured Note-Taking:
  • :TypstDailyNote: A zero-friction command to open today's note in your notes directory.
  • :TypstClassNote: Prompts you to select a course and creates a new, dated note in the correct subfolder.
• Template-Based Creation: New notes are created from your custom templates, pre-filling boilerplate content.
• Context-Aware Snippets: Optional integration with LuaSnip provides powerful snippets that only trigger in the right context (e.g., inside or outside of a math block).
• Aggressive Git Autopush: An opt-in feature that will automatically add, commit, and push your changes after every save. Includes an automatic history-squashing mechanism to keep your git history clean.

Requirements

• Neovim >= 0.8.0
• typst installed and available in your PATH.
• Optional:
  • LuaSnip for snippet support.
  • nvim-treesitter for context-aware snippets.

Installation

Install using your favorite package manager. Here is an example with lazy.nvim:

-- lua/plugins/typst-notes.lua
{
    "pseudofractal/typst-notes.nvim",
    -- lazy = false, -- or ft = "typst"
    config = function()
        require("typst").setup({
            -- Your configuration goes here
        })
    end,
}

Configuration

Here is the default configuration with explanations for all available options. You only need to include the keys you wish to override.

-- In your config function:
require("typst").setup({
  -- Controls the integrated PDF viewer.
  pdf_preview = {
    enable = false, -- Set to true to automatically open PDFs.
    -- Command to open a PDF file. Defaults to 'xdg-open' on Linux.
    -- Examples:
    --   opener = "open" -- macOS
    --   opener = "start" -- Windows
    --   opener = "zathura"
    opener = "",
    delay = 1000, -- Delay in milliseconds before opening the PDF.
  },

  -- Settings for note-taking commands.
  notes = {
    daily = {
      -- Directory for daily notes, e.g., '~/notes/daily'.
      -- Must be set for :TypstDailyNote to work.
      path = "",
      -- Path to the template file for daily notes.
      template_file_path = "",
    },
    class = {
      -- Parent directory containing one sub-folder per course,
      -- e.g., '~/notes/university'.
      -- Must be set for :TypstClassNote to work.
      parent = "",
      -- The sub-folder within each course directory where notes are stored.
      folder_name = "Class", -- e.g., '~/notes/university/Math/Class'
      -- The name of the template file to use. The plugin will look for this
      -- file inside each course's main directory.
      template_file_name = "template.typ",
    },
  },

  -- Automatically commit and push changes.
  git = {
    enable = false, -- Disabled by default for safety.
    -- After this many commits, the history will be squashed into a
    -- single commit and force-pushed.
    max_commits_on_local = 20,
  },

  -- Enable or disable snippet support.
  -- Requires LuaSnip and nvim-treesitter.
  snippets = {
    enable = true,
  },
})

⚠️ Git Autopush Warning

The git.enable = true feature is designed for a very specific workflow where a notes repository is treated more like a live backup than a collaborative software project.

• On every save (:w) of a .typ file, it runs git add . and git commit.
• When the number of local commits exceeds max_commits_on_local, it will automatically run git reset --soft HEAD~N and git push --force.

This overwrites the remote history. Do NOT enable this feature if multiple people are collaborating on the repository or if you are working on the same repository from multiple machines without pulling first. You risk losing work.

Usage

Commands

• :TypstOpenPDF Manually opens the PDF for the current Typst file.

• :TypstDailyNote Creates and opens a new note for the current day, using your configured daily path and template. The file will be named dd-mm-yyyy.typ.

• :TypstClassNote Presents a vim.ui.select prompt with all the course folders found in your class.parent directory. After you select a course, it creates and opens a new dd-mm-yyyy.typ note inside that course's notes sub-folder.

Snippets

If snippets.enable is true, the plugin will load several useful snippets for Typst. They are context-aware and will only trigger when appropriate.

Trigger	Context	Expands to...
mk	Outside Math	$${1}$ (inline math)
dm	Outside Math	$\n ${1}\n$ (display math)
==	Inside Math	&= (for aligned equations)
^	Inside Math	^(${1}) (superscript)
_	Inside Math	_(${1}) (subscript)
a/	Inside Math	(a)/(${1}) (fraction)
vv	Inside Math	va(${1}) (vector arrow)

...and more. See snippets/typst.lua for the complete list.

License

This project is licensed under the MIT License. See the LICENSE file for details.