Smarana (स्मरण)

Smarana is a knowledge management and note-taking system built for Typst. It combines the structured approach of a Zettelkasten with the beautiful typesetting capabilities of Typst, providing a seamless flow between capturing fleeting thoughts and developing permanent, interconnected knowledge.

The system is built around a Rust-based CLI that manages a local SQLite database for fast indexing and search, while the documents themselves remain plain Typst files. This ensures your knowledge base is both future-proof and highly performant.

Key Features

• Categorized Note Types: Organize knowledge into Fleeting (transient ideas), Capture (literature and reference notes), and Atomic (permanent, interconnected concepts) notes.
• Automatic Tag Appendix: Every tag used in your notes is automatically indexed at the end of your notebook with clickable reference links.
• Native Cross-Linking: Use standard Typst references to link between notes. Smarana ensures these links stay resolved and easily navigable.
• Live Preview: Integrated support for live rendering of the entire notebook or individual notes using typst-preview.
• Flexible Organization: Notes are managed via a database, allowing you to focus on content rather than directory hierarchies.

Installation

CLI Tool

The core of Smarana is the Rust CLI. You can install it via cargo:

cargo install --git https://codeberg.org/scientiac/smarana.git

This will provide the sma command globally.

Typst Setup

Smarana requires typst to be installed on your system. You can find installation instructions at the official Typst repository.

Neovim Plugin

For the best experience, Smarana is designed to be used with Neovim. You will also need typst-preview.nvim for live visualization.

Example Configuration

Below is a complete setup using a standard plugin manager syntax. This configuration handles auto-start previews, global notebook resolution, and convenient keymaps.

-- Typst Preview Setup (Essential for visualization)
vim.pack.add({ { src = "https://github.com/chomosuke/typst-preview.nvim" } })

local ok, typst_preview = pcall(require, "typst-preview")
if ok then
  typst_preview.setup({
    formatterMode = "typstyle",
    open_cmd = 'previewfox %s'
  })
end

-- Smarana Setup
vim.pack.add({ { src = "https://codeberg.org/scientiac/smarana.git" } })

local ok_sma, smarana = pcall(require, "smarana")
if ok_sma then
  smarana.setup({
    preview = true,       -- Automatically starts preview when opening notes
    default_type = "ask", -- Options: "ask", "fleeting", "capture", "atomic"
  })

  -- Normal mode mappings
  local map = vim.keymap.set -- or your custom mapper
  
  map("n", "<leader>sn", ":SmaNew<cr>", { desc = "New note (type picker)" })
  map("n", "<leader>ss", ":SmaNotes<cr>", { desc = "Search notes" })
  map("n", "<leader>sk", ":SmaInsertLink<cr>", { desc = "Insert @ref link" })
  map("n", "<leader>sS", ":SmaSync<cr>", { desc = "Manual database sync" })

  -- Quick shortcuts for specific types
  map("n", "<leader>sf", ":SmaNewFleeting<cr>", { desc = "New fleeting note" })
  map("n", "<leader>sc", ":SmaNewCapture<cr>", { desc = "New capture note" })
  map("n", "<leader>sa", ":SmaNewAtomic<cr>", { desc = "New atomic note" })

  -- Visual mode mappings for rapid note creation
  map("v", "<leader>st", smarana.new_from_title, { desc = "New note from selection (title)" })
  map("v", "<leader>sc", smarana.new_from_content, { desc = "New note from selection (body)" })
  map("v", "<leader>sl", smarana.insert_link_at_selection, { desc = "Link selection to note" })
end

Getting Started

1. Initialize a Notebook: Navigate to the directory where you want to store your notes and run:

   sma -I
   

   This creates a .smarana directory containing your configuration, templates, and the SQLite index.

2. Configure Global Path: Smarana can be used from anywhere if you register your notebook path in the global config. The initialization process usually handles this, but you can check it in ~/.config/smarana/config.toml.

3. Check Your Configuration: Before you start taking notes, it is recommended to review the configuration file inside your notebook's .smarana directory named config.toml to set it up to your liking:

   sma -c
   

4. Create Your First Note: Use sma -n "My First Note" or the :SmaNew command in Neovim.

5. Synchronize: If you manually move or edit files, run sma -s to keep the database and the smarana.typ master document up to date.

How it Works

Smarana treats every note as a Typst document that imports a central library.typ. When you sync your notebook, the CLI performs several tasks:

• It parses the frontmatter of every .typ file in your root directory.
• It updates a local SQLite database with metadata like titles, dates, and tags.
• It regenerates the smarana.typ file, which includes all your notes organized by category, separated by visual dividers, and concluded with the Tag Appendix.
• It ensures that all cross-references resolved via @label syntax work across the entire notebook.

By separating the content (Typst files) from the organization (SQLite + master document), Smarana allows your knowledge base to scale to thousands of notes without becoming unmanageable.