smarana 0.7.3

An extensible note taking system for typst.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

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

```bash
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](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 a standard 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. **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.

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:
   ```bash
   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.