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)

cargo install ekphos

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

and after the container is up, you can SSH into the machine with the following command ssh ekphos@your-docker-container-ip

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

cargo install ekphos

sudo make uninstall

cargo uninstall ekphos

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

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

Note: This configuration format requires v0.3.0 or later. Earlier versions have a broken config system, please upgrade to v0.3.0 to enjoy proper configuration and theming support.

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

• catppuccin-mocha (default)

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 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. Copy the theme file (e.g., dracula.toml) to your themes directory:

   # Example: Download Dracula theme
   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 using the filename (without .toml):

   # ~/.config/ekphos/config.toml
   theme = "dracula"

Theme naming convention:

Note: Alacritty theme compatibility requires v0.3.0 or later. Earlier versions have a broken theming system.

Ekphos has three panels:

• Sidebar (left): List of notes
• Content (center): Note content with markdown rendering
• Outline (right): Auto-generated headings for quick navigation

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.

1. Select the note in the sidebar
2. Press r to rename
3. Edit the note name (pre-filled with current name)
4. Press Enter to confirm or Esc to cancel

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

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

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

Use standard markdown image syntax:

![alt text](path/to/image.png)
![screenshot](~/pictures/screenshot.png)
![diagram](./diagrams/flow.png)

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
• 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

Ekphos is open source and contributions are welcome.

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

• main - Development branch
• release - Stable release branch

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, so there will 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, go create a discussion in this repo for how socials should be done

MIT