easymd

English · 中文

A terminal Markdown editor: vim-style editing on the left, live preview on the right. Built with Textual.

Install

Requires Python 3.10+. Install from PyPI with pip or uv:

pip install easymd-cli      # or: uv tool install easymd-cli
easymd notes.md             # created on the first :w if it does not exist

For one-key translation of the preview (see Translation), add the optional extra:

pip install 'easymd-cli[translate]'   # or: uv tool install 'easymd-cli[translate]'

From source:

git clone https://github.com/decajoin/easymd && cd easymd
uv sync --group dev
uv run easymd demo.md
uv run pytest            # run the tests

Key reference

Modes

Motions (normal/visual mode, count prefixes like 3j)

h j k l, w b e, 0 ^ $, gg G (3G jumps to line 3), { } paragraphs, Ctrl+d/u half-page, Ctrl+f/b full-page.

Editing

Commands and search

Translation (DeepSeek)

With the [translate] extra installed, :trans translates the whole preview (into Chinese by default) and caches it; :trans again switches back to the original. The document is split into Markdown blocks and cached by content, so after editing the status bar shows "translation out of date" and :refresh re-translates only the changed blocks. Translation affects the preview only — it is never written back to your file.

:summarize (alias :sum) reuses the same pipeline to produce a short TL;DR in the same target language as translation. :refresh re-runs whichever AI view is active.

Output streams in token by token, so it appears as it is produced. Results are cached on disk under ~/.cache/easymd/translate/, so re-translating the same content costs nothing (set EASYMD_CACHE_DIR= empty to disable, or point it elsewhere). In translation view the preview scrolls in step with the editor by heading section; the summary view, being condensed, scrolls independently.

If the [translate] extra is missing or no API key is configured, :trans / :summarize show a friendly notice in the status bar instead of crashing.

Configuring the API key

Environment variable first, then the config file ~/.config/easymd/config.toml:

export DEEPSEEK_API_KEY=sk-...        # recommended
# or write it to the config file interactively (mode 0600):
easymd config set-key

Config file example:

[deepseek]
api_key = "sk-..."          # or the DEEPSEEK_API_KEY env var (takes priority)
model = "deepseek-v4-flash" # or deepseek-v4-pro
target_lang = "中文"

Related: easymd config show (resolved config, key masked) and easymd config set-model deepseek-v4-pro. You can also override at launch: easymd --pro notes.md, easymd --model <id> notes.md, easymd --lang English notes.md.

Project layout

src/easymd/
  cli.py        # entry point (typer: easymd FILE / easymd config ...)
  app.py        # split layout, status bar, command line, preview sync, AI views
  editor.py     # vim modal layer (TextArea subclass)
  config.py     # read DeepSeek config (env > config.toml > defaults)
  translate.py  # chunking + content cache + DeepSeek client (optional dep)
tests/          # pytest suite (Textual Pilot drives real key presses headless)

Run the tests with uv run pytest.