Smarana (स्मरण)

Smarana is a knowledge management and note-taking system built with typst in mind. 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 are 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.

Showcase

This is using neovim with the neovim plug-in present in this repo, typst-preview.nvim for preview, tinymist as LSP and obviously smarana's CLI sma as the backend.

Notes edited with Neovim and previewed with Typst Preview

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
# or 
cargo install smarana

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 neovim's built-in 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. Get Help: Run sma -h or sma --help to know about the different CLI features.

2. 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.

3. 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, you can check it in ~/.config/smarana/config.toml.

4. 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
   

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

6. Synchronize: If you manually move or edit files, run sma -s to sync the notes with the database which will also update related files like smarana.typ with proper structure.

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 without becoming unmanageable.