XDG Package System Guide

Overview

Typstwriter.nvim uses an XDG-compliant package system that stores the typstwriter package and bundled fonts in system data directories, separate from your templates. This ensures consistent typography across platforms and follows OS conventions for application data storage.

Architecture

XDG-Compliant Storage

Separation of Concerns

First-Time Setup

After installing typstwriter.nvim with your plugin manager, run:

1

:TypstWriterSetup

This command will:

  1. Install the typstwriter package to XDG-compliant directories
  2. Install professional fonts (~32MB) for consistent typography
  3. Install template files with correct absolute import paths
  4. Verify everything is working correctly

Available Commands

:TypstWriterSetup

Complete setup - installs package, fonts, and templates (recommended for first-time users)

:TypstWriterPackageStatus

Check XDG installation status and see what’s installed

:TypstWriterInstallPackage

Install/update just the package and fonts (without templates)

:TypstWriterSetupTemplates

Install/update just the templates (without package/fonts)

What Gets Installed

XDG Package Installation

Linux Example (~/.local/share/nvim/typstwriter/):

1
2
3
4
5
6
7
8
9
10
11
12
13
14

~/.local/share/nvim/typstwriter/
├── package/
│   ├── typst.toml           # Package manifest
│   ├── lib.typ              # Main library entry point
│   ├── core/                # Core styling functions
│   │   ├── base.typ         # Base typography and layout
│   │   ├── document.typ     # Document structure
│   │   └── metadata.typ     # Metadata handling
│   ├── themes/              # Theme definitions
│   └── components/          # Reusable components
└── fonts/                   # Bundled professional fonts (~32MB)
    ├── IosevkaNerdFont-Regular.ttf
    ├── HackNerdFont-Regular.ttf
    └── NotoColorEmoji.ttf

Template Directory

Your configured template_dir:

1
2
3
4
5
6

templates/
├── meeting.typ              # Meeting notes template
├── note.typ                 # General note template
├── project.typ              # Project documentation template
├── article.typ              # Article template
└── report.typ               # Report template

Template Files

Import Paths in Templates

Templates use absolute imports to the XDG installation:

#import "/home/user/.local/share/nvim/typstwriter/package/lib.typ": *

#metadata((
  title: "Document Title",
  date: "2025-08-16",
  status: "draft",
))

#show: note_template

= Document Title

Content using bundled fonts and consistent styling.

Path Resolution:

Font System

Bundled Fonts (~32MB)

Font Path Integration

Configuration

Basic Configuration

1
2
3
4
5

require("typstwriter").setup({
  notes_dir = "~/Documents/notes",
  template_dir = "~/Documents/notes/templates", -- Templates here, package in XDG
  -- ... other config
})

XDG Directory Override (Advanced)

By default, the plugin uses standard XDG directories. You typically don’t need to change this, but if required:

1
2
3
4
5
6
7

-- Note: This is usually not necessary - XDG directories are auto-detected
require("typstwriter").setup({
  -- Standard user configuration
  notes_dir = "~/Documents/notes",
  template_dir = "~/Documents/notes/templates",
  -- XDG directories are handled automatically
})

Troubleshooting

“Package not installed” warning

Import errors in templates

Font issues

Templates not found

Permission issues

Updating

When you update typstwriter.nvim:

Benefits of XDG System

For Users

For Developers