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

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

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

If installed with Cargo:

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
syntax_theme = "base16-ocean.dark"

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:

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:

Ekphos has three panels:

Use Tab or Shift+Tab to switch between panels.

The sidebar displays a hierarchical folder tree that automatically detects subdirectories containing .md files:

• Folders are shown with ▶ (collapsed) or ▼ (expanded) icons
• Press Enter on a folder to toggle expand/collapse
• Folders and notes are sorted alphabetically together
• Folders start collapsed by default

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)

Code blocks with a language specifier are syntax-highlighted using syntect:

```rust
fn main() {
    let message = "Hello, Ekphos!";
    println!("{}", message);
}
```

Supported languages: Rust, Python, JavaScript, TypeScript, Go, C, C++, Java, Ruby, PHP, Shell, SQL, HTML, CSS, JSON, YAML, Markdown, and many more.

Code blocks without a language specifier render in a uniform green color.

Available syntax themes:

Set in config:

# ~/.config/ekphos/config.toml
syntax_theme = "base16-mocha.dark"

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. Click on the image or press Enter/o to open in system viewer

For inline image preview, use a compatible terminal:

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

Markdown links are rendered with underlined cyan text:

[Ekphos Website](https://ekphos.xyz)
[GitHub](https://github.com)

Opening links:

• Click on a link to open in your default browser
• Or navigate to the line and press Space
• Hover over a link to see the "Open ↗" hint

Multiple links on same line:

• Use ] to select next link, [ to select previous
• Selected link is highlighted with yellow background
• Space opens the currently selected link

Use HTML <details> tags for collapsible/expandable sections:

<details>
<summary>Click to expand</summary>

Hidden content goes here.
This can include multiple lines.

</details>

Usage:

• Click on the details line to toggle open/close
• Or navigate with keyboard and press Space
• When collapsed, shows ▶ indicator
• When expanded, shows ▼ indicator with content below

Use cases: FAQs, spoilers, optional information, long code examples.

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