asterism 0.5.5

Hyperbolic navigation for tree data
Documentation 
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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# ⁂  asterism

[![crates.io](https://img.shields.io/crates/v/asterism.svg)](https://crates.io/crates/asterism)
[![documentation](https://docs.rs/asterism/badge.svg)](https://docs.rs/asterism)
[![MIT licensed](https://img.shields.io/crates/l/asterism.svg)](./LICENSE)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/lmmx/asterism/master.svg)](https://results.pre-commit.ci/latest/github/lmmx/asterism/master)

Hyperbolic navigation for tree data

![You are here](https://github.com/user-attachments/assets/26c005dc-5444-458e-ad58-b506fa9518c6)

> You are here

## vim-like document section editor

asterism uses ratatui to give a hierarchical tree navigator for markdown documents,
and [edtui][edtui] to emulate a vim editor in which to edit section content.

[edtui]: https://github.com/preiter93/edtui

## Features

- Tree-sitter based markdown parsing
- Hierarchical section navigation with parent/child relationships
- Section reordering from the header outline
- Visual line wrapping with configurable width
- Multi-file support with directory tree display
- Edit sections without modifying heading markup
- Vim-like keybindings for efficient editing

## Installation

Regular cargo install or (recommended) install the pre-built binary with:
```sh
cargo binstall asterism
```

## Usage

Edit markdown files in the current directory:
```sh
asterism
```

Edit a specific file:
```sh
asterism README.md
```

## Difftastic Integration

asterism can display and navigate difftastic structural diffs:

![Difftastic Asterism demo](https://github.com/user-attachments/assets/c29b3271-4a55-42dd-bcf3-97fb8aaad89f)

- Viewing/editing of the diff chunks TODO! (WIP)

### From a JSON file:
```sh
DFT_DISPLAY=json DFT_UNSTABLE=yes difft file1.rs file2.rs > diff.json
asterism -d diff.json
```

### From stdin:
```sh
DFT_DISPLAY=json DFT_UNSTABLE=yes difft file1.rs file2.rs | asterism --stdin
```

### From git:
```sh
DFT_DISPLAY=json DFT_UNSTABLE=yes git -c diff.external=difft diff --cached | asterism -d --stdin
```

### As a git difftool:
```sh
# In .gitconfig:
[diff]
    tool = asterism-difft
[difftool "asterism-difft"]
    cmd = difft --display json \"$LOCAL\" \"$REMOTE\" | asterism --stdin
```

In difftastic mode:
- Files are shown as top-level sections
- Each diff hunk appears as a nested section
- Navigate and review changes hierarchically
- Hunks display with line numbers and +/- prefixes

## Keybindings

### List View

- <kbd>↑</kbd>/<kbd>↓</kbd>: Jump to previous/next sections
  - <kbd>Shift</kbd> + <kbd>↑</kbd>/<kbd>↓</kbd>: Jump to previous/next section at same level
- <kbd>←</kbd>/<kbd>→</kbd>: Jump to parent section/next descendant
- <kbd>Home</kbd>/<kbd>End</kbd>: Jump to first/last section in document
  - <kbd>Shift</kbd> + <kbd>Home</kbd>/<kbd>End</kbd>: Jump to first/last section at same level
- <kbd>Enter</kbd>: Edit section
- <kbd>q</kbd>: Quit (or return to file list in multi-file mode)

#### Section Reordering

- <kbd>Ctrl</kbd> + <kbd>↑</kbd>/<kbd>↓</kbd>/<kbd>←</kbd>/<kbd>→</kbd>: Activate move mode (section turns orange), then move section up/down/in/out
- <kbd>Ctrl</kbd> + <kbd>←</kbd>/<kbd>→</kbd>: Change heading level (dedent/indent)
- <kbd>Ctrl</kbd> + <kbd>Home</kbd>/<kbd>End</kbd>: Move section to top/bottom of document
- <kbd>:w</kbd>: Save reordered structure to disk
- <kbd>Esc</kbd>: Cancel move operation

When moving, the selected section displays in orange, then turns red after being repositioned to indicate unsaved changes.

### Editor View

- <kbd>:w</kbd>: Save
- <kbd>:x</kbd>: Save and exit
- <kbd>:q</kbd>: Quit (warns if unsaved)
- <kbd>:q!</kbd>: Force quit
- <kbd>:wn</kbd>: Save and go to next header
- <kbd>:wp</kbd>: Save and go to previous section
- Standard vim editing commands

## Configuration

Create an `asterism.toml` file in your project directory:
```toml
wrap_width = 100
file_extensions = ["md", "markdown"]
```

## Licensing

Asterism is [MIT licensed](https://github.com/lmmx/asterism/blob/master/LICENSE), a permissive open source license.