# 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](https://codeberg.org/scientiac/smarana/media/branch/main/showcase.png)

## Installation

### CLI Tool

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

```bash
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](https://github.com/typst/typst).

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

```lua
-- 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.
1. **Initialize a Notebook**: Navigate to the directory where you want to store your notes and run:
   ```bash
   sma -I
   ```
   This creates a `.smarana` directory containing your configuration, templates, and the SQLite index.

1. **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`.

1. **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:
   ```bash
   sma -c
   ```

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

1. **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.
