smep 0.1.8

A Simple Markdown Editor & Previewer, written in Rust
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

# smep — a Simple Markdown Editor & Previewer, written in Rust

[![crates.io](https://img.shields.io/crates/v/smep.svg)](https://crates.io/crates/smep)
[![CI](https://github.com/newdee/smep/actions/workflows/ci.yml/badge.svg)](https://github.com/newdee/smep/actions/workflows/ci.yml)
[![license](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)

**smep** is a markdown editor with live preview, built in pure Rust on the
[GPUI](https://www.gpui.rs) framework (the UI toolkit behind the Zed editor).
A frameless window with a small menu bar in its title bar (hide it with a
shortcut), and three views: source, split, and a rendered view you edit in
place, block by block.

## Status

`0.1.8` is the ninth release: on a Mac, `brew install --cask newdee/tap/smep`
installs `smep.app` (Finder, Spotlight, the Dock, "Open With", no Terminal
window) together with the `smep` command. Reading mode scrolls from the
keyboard and renders `.html` files as pages, `smep notes.md` opens a new
document when the file is not there yet, and the Windows "Open Markdown
Files with smep" no longer flashes a console. It opens reading, and Ctrl+E
/ Cmd+E or the Edit button in the title bar brings the editor. On Windows
it opens without a terminal window. It wears the Paper look (keepane's paper and paper-dark, light or
dark with the system) and can make itself the default app for Markdown
from the File menu, on top of importing PDF, Word, HTML
and text files as Markdown, exporting the document as a PDF or an HTML
page, the frameless window with its view modes, in-place editing in the
rendered view, opening files from the OS, a Homebrew formula, and typing
that stays smooth in large documents. Expect rough edges; the editor and
preview are built on gpui-kit and gpui-pre, which are themselves young.

## What it does

- Source, split (resizable) or rendered view; the preview updates as you type.
- The rendered view edits in place: click a block and it turns into its
  Markdown source, sized to its text; click elsewhere or press Escape and it
  renders again. A click below the last block starts a new one; `/` there
  opens the block menu.
- Frameless window: File / Edit / View menus live in the title bar and can be
  hidden; full screen on a key.
- A menu of blocks (headings, lists, task list, quote, code block, table,
  divider, image, link) wherever you ask for it: type `/` on an empty line,
  click the `+` beside one, click below the end of the text, or right-click.
- Preview themes (Paper and Paper Dark, GitHub, Newsprint, Night, Sepia,
  Solarized Light/Dark, or the application's own look): right-click the
  preview or the rendered document. The choice is remembered in
  `settings.toml` under the platform config directory.
- Opens reading: the document rendered, nothing to click into by accident,
  and the keyboard scrolls it (Page Up / Page Down, Space, Home / End, the
  arrows). The Edit button in the title bar (or Ctrl+E) brings the editor
  in the view mode you last used; Read (or Ctrl+E again) puts it away.
- Markdown highlighting in the editor from the same parser the preview uses.
- The preview follows the editor: whatever block is at the top of the editor
  is at the top of the preview.
- CommonMark + GFM: tables, task lists, strikethrough, footnotes. Raw HTML
  inside Markdown renders too, and `.html` files open straight into the
  HTML preview.
- Open, save, save as; an unsaved-changes prompt before closing.
- Other documents become Markdown: drop a PDF, Word (.docx) or text file on
  the window, pick one under File, Import as Markdown (HTML too), or pass it
  on the command line. The result is a new, unsaved document named after
  the original. PDFs need a text layer; smep does no OCR. Images in Word
  files are not carried over.
- Export as PDF (typeset by [Typst](https://typst.app), built in: headings,
  lists, tables, code, quotes, footnotes, local images; CJK text uses the
  system's fonts) or as a standalone HTML page, under File.
- Ink on paper: the application wears keepane's Paper look, light or dark
  with the system (warm cream or warm near-black, Vitesse hues, cinnabar
  for the cursor and headings).
- One static binary, no web view, no Electron.

## Keys

| Action | Windows / Linux | macOS |
|---|---|---|
| Open | Ctrl+O | Cmd+O |
| Import as Markdown | Ctrl+Shift+O | Cmd+Shift+O |
| Save | Ctrl+S | Cmd+S |
| Save as | Ctrl+Shift+S | Cmd+Shift+S |
| Export as PDF | Ctrl+Shift+E | Cmd+Shift+E |
| Edit, or back to reading | Ctrl+E (or the Edit / Read button) | Cmd+E (or the button) |
| Scroll the rendered document | Page Up / Page Down, Space / Shift+Space, Home / End, ↑ / ↓ | same |
| Source / Split / Rendered view (starts editing) | Ctrl+1 / 2 / 3 | Cmd+1 / 2 / 3 |
| Show or hide the menu bar | Ctrl+Shift+M | Cmd+Shift+M |
| Full screen | F11 | Ctrl+Cmd+F |
| Insert block (on an empty line) | `/` | `/` |
| Edit a block in the rendered view | click it | click it |
| Finish editing a block | Escape (or click elsewhere) | Escape (or click elsewhere) |
| Block menu / clipboard | right-click the editor | right-click the editor |
| Preview theme | right-click the preview or the rendered document | same |
| Find in editor | Ctrl+F | Cmd+F |
| Find and replace | Ctrl+H | Cmd+Shift+F |
| Document start / end | Ctrl+Home / Ctrl+End | Cmd+Up / Cmd+Down |

## Install

```sh
cargo install smep
smep notes.md
```

A file that does not exist yet opens as a new document and is written there
on the first save. On a Mac, Homebrew installs the application:

```sh
brew install --cask newdee/tap/smep
```

The cask puts `smep.app` in `/Applications` (Finder, Spotlight, the Dock,
"Open With", the default app for `.md`) and links its binary as the `smep`
command; both follow new releases by themselves. The app is Developer ID
signed but not yet notarized, so the first start from Finder is refused
once: allow it under System Settings, Privacy & Security, Open Anyway, or
install with `brew install --cask --no-quarantine newdee/tap/smep`.

A bare binary (`cargo install`, the formula `brew install newdee/tap/smep`,
the release tarball) is a command-line tool to macOS: Finder, Spotlight
and "Open With" run it inside a Terminal window, and only an application
can claim `.md` files. Take the cask or the release's `smep.app` for that.
(No Linux formula: that binary needs the system's X11, xkbcommon, Wayland
and Vulkan libraries, which a Homebrew prefix does not provide; use `cargo
install` or the release tarball there.) `smep --version` and `smep --help`
print and exit without opening a window. On Windows smep is a GUI program:
no terminal window comes up with it, and in a terminal it still prints.
PowerShell neither waits for a GUI program nor captures its output, so a
script there asks through `cmd /c smep --version` (or `Start-Process -Wait
-RedirectStandardOutput`).

Building from source needs a Rust toolchain and, on Linux, a few system
libraries; see [docs/dev.md](docs/dev.md). PDF import and PDF export are
the two heavy parts of the binary (about 7 MB and 34 MB); a build without
them, `cargo install smep --no-default-features`, keeps everything else
and reports the missing feature if asked for it.

## Make it the default for `.md`

File, "Open Markdown Files with smep" does what the system allows:

- **macOS**: smep claims Markdown files outright, when it runs as
  `smep.app` (the Homebrew cask or a GitHub release; a `cargo install` or
  formula binary has no bundle, so Finder cannot pick it, and the menu item
  says so). Files opened from Finder land in the running window. The app
  is Developer ID signed but not yet notarized, so the first open from
  Finder needs System Settings, Privacy & Security, Open Anyway (older
  systems: right-click, Open).
- **Windows**: smep registers itself (current user, no admin) and opens the
  Settings page for it, where you choose smep next to `.md` once; Windows
  keeps that choice to itself. `scripts\register-windows.ps1` does the same
  registration from a terminal.
- **Linux**: smep writes `~/.local/share/applications/smep.desktop` and runs
  `xdg-mime default smep.desktop text/markdown`. (`assets/smep.desktop` is
  the same file, for doing it by hand.)

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this work by you shall be dual licensed as above, without any
additional terms or conditions.