⁂ asterism

Hyperbolic navigation for tree data

vim-like document section editor

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

You are here

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:

cargo binstall asterism

Usage

Edit markdown files in the current directory:

asterism

Edit a specific file:

asterism README.md

Difftastic Integration

asterism can display and navigate difftastic structural diffs:

From a JSON file:

difft --display json file1.rs file2.rs > diff.json
asterism -d diff.json

From stdin:

difft --display json file1.rs file2.rs | asterism --stdin

As a git difftool:

# 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

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

Section Reordering

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

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

Editor View

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

Configuration

Create an asterism.toml file in your project directory:

wrap_width = 100
file_extensions = ["md", "markdown"]

Licensing

Asterism is MIT licensed, a permissive open source license.