Crates.io Rust License

An open source, lightweight, fast, terminal-based markdown research tool built with Rust.

Ekphos Preview

• Getting Started
  • Requirements
  • Installation
    • Using Cargo (Recommended)
    • Using Make
    • Using Docker
  • Update
  • Uninstall
  • CLI Options
  • Configuration
    • Config File
    • Themes
      • Bundled Theme
      • Using Alacritty Themes
      • Custom Themes
  • Usage
    • Layout
    • Creating Notes
    • Creating Folders
    • Renaming
    • Deleting
    • Searching Notes
    • Editing Notes
    • Markdown Support
    • Images
      • Adding Images
      • Viewing Images
      • Terminal Image Support
    • Using the Outline
  • Keyboard Shortcuts
    • Global
    • Sidebar
    • Content View
    • Edit Mode
      • Normal Mode
      • Delete Commands Flow
    • Visual Mode
  • Contributing
    • Development Setup
    • Branch Strategy
    • Workflow
  • Disclaimer
  • Socials
  • License

• Rust 1.70+ (run rustup update to update)
• A terminal emulator (for inline image preview: iTerm2, Kitty, WezTerm, Ghostty, or Sixel-compatible terminal)

cargo install ekphos

git clone https://github.com/hanebox/ekphos.git
cd ekphos
make
sudo make install

git clone https://github.com/hanebox/ekphos.git
cd ekphos
docker build -t ekphos-ssh .
docker compose up -d

After the container is up, SSH into the machine:

ssh ekphos@your-docker-container-ip

cargo install ekphos

If installed with Cargo:

cargo uninstall ekphos

If installed with Make:

cd ekphos # navigate to the cloned repo
sudo make uninstall

Configuration is stored in ~/.config/ekphos/config.toml.

# ~/.config/ekphos/config.toml
notes_dir = "~/Documents/ekphos"
welcome_shown = false
theme = "catppuccin-mocha"
show_empty_dir = true

Note: This configuration format requires v0.3.0 or later.

Experimental: Themes are still highly experimental. We expect to finalize the theme standard around v0.6.0 or v0.7.0.

Themes are stored in ~/.config/ekphos/themes/ and use the Alacritty color scheme format.

• catppuccin-mocha (default)

Ekphos is fully compatible with Alacritty Themes. To use any Alacritty theme:

1. Browse themes at https://github.com/alacritty/alacritty-theme/tree/master/themes
2. Download a theme file to your themes directory:

   curl -o ~/.config/ekphos/themes/dracula.toml \
    https://raw.githubusercontent.com/alacritty/alacritty-theme/master/themes/dracula.toml

3. Set the theme in your config:

   theme = "dracula"

Create a .toml file in the themes directory using the Alacritty color format:

# ~/.config/ekphos/themes/mytheme.toml
[colors.primary]
background = "#1e1e2e"
foreground = "#cdd6f4"
[colors.cursor]
text = "#1e1e2e"
cursor = "#f5e0dc"
[colors.selection]
text = "#1e1e2e"
background = "#f5e0dc"
[colors.normal]
black = "#45475a"
red = "#f38ba8"
green = "#a6e3a1"
yellow = "#f9e2af"
blue = "#89b4fa"
magenta = "#f5c2e7"
cyan = "#94e2d5"
white = "#bac2de"
[colors.bright]
black = "#585b70"
red = "#f38ba8"
green = "#a6e3a1"
yellow = "#f9e2af"
blue = "#89b4fa"
magenta = "#f5c2e7"
cyan = "#94e2d5"
white = "#a6adc8"

Then set in config:

theme = "mytheme"

Ekphos has three panels:

Use Tab or Shift+Tab to switch between panels.

1. Press n to create a new note
2. Enter the note name
3. Press Enter to confirm

Notes are stored as .md files in your configured notes directory.

Context-aware: When your cursor is on a folder or a note inside a folder, pressing n will create the new note in that folder.

1. Press N (Shift+N) to create a new folder
2. Enter the folder name
3. Press Enter to confirm
4. A dialog will appear to create the first note in the folder
5. Enter the note name and press Enter (or Esc to cancel and remove the empty folder)

Context-aware: When your cursor is on a folder, pressing N will create the new folder as a subfolder.

1. Select a note or folder in the sidebar
2. Press r to rename
3. Edit the name and press Enter to confirm (or Esc to cancel)

1. Select a note or folder in the sidebar
2. Press d to delete
3. Confirm with y or cancel with n

Warning: Deleting a folder will remove all notes inside it!

1. Press / in the sidebar to start searching
2. Type your search query
3. Results are highlighted in green, title shows match count
4. Use Arrow keys or Ctrl+j/k/n/p to navigate between matches
5. Press Enter to select and close search
6. Press Esc to cancel search

Features:

• Searches all notes recursively, including those in collapsed folders
• Auto-expands folders containing matched notes
• Border color indicates status: yellow (typing), green (matches found), red (no matches)

1. Select a note in the sidebar
2. Press e to enter edit mode
3. Edit using vim keybindings
4. Press Ctrl+s to save
5. Press Esc to exit edit mode (discards unsaved changes)

Use standard markdown image syntax:

![alt text](path/to/image.png)
![screenshot](~/pictures/screenshot.png)
![diagram](./diagrams/flow.png)
![remote](https://example.com/image.png)

Both local files and remote URLs (http/https) are supported.

Supported formats: PNG, JPEG, GIF, WebP, BMP

1. Navigate to the image line in content view
2. Press Enter or o to open in system viewer

For inline image preview, use a compatible terminal:

• iTerm2 (macOS)
• Kitty
• WezTerm
• Ghostty
• Sixel-enabled terminals

The outline panel shows all headings in your note:

1. Press Tab to focus the outline
2. Use j/k to navigate headings
3. Press Enter to jump to that heading

Floating Cursor Mode: When enabled (yellow border, [FLOAT] indicator), the cursor moves freely within the visible area. The view only scrolls when the cursor reaches the top or bottom edge. Toggle with Shift+J or Shift+K.

Delete commands (dd, dw, db) use a confirmation flow with visual feedback:

1. Press d - Title shows NORMAL d- with yellow border
   • Available: d (line), w (word forward), b (word backward)
2. Press target key - Text is highlighted, title shows NORMAL [DEL] with red border
   • Press d to confirm deletion
   • Press Esc to cancel
   • Any other key cancels and performs its action

Press v in normal mode to enter visual mode for text selection.

Ekphos is open source and contributions are welcome.

git clone https://github.com/hanebox/ekphos.git
cd ekphos
make run

1. Fork the repository
2. Create a feature branch from main
3. Make your changes
4. Submit a PR to the main branch

This project is in an early development stage. There may be frequent unexpected breaking changes throughout the pre-release, but things should remain usable throughout this stage.

We don't have socials yet, but things are open for discussion. Feel free to create a discussion in this repo.

MIT