landon
7271e5e2ef
A 📂 button beside each path field opens a native picker: a folder chooser for the workspace and an .odt save dialog for the export (which appends the extension if omitted). Uses rfd with the XDG Desktop Portal backend, so there is no GTK build dependency and no new shared library at runtime. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
128 lines
4.7 KiB
Markdown
128 lines
4.7 KiB
Markdown
# md-manuscript
|
||
|
||
A small desktop application for Debian that treats a directory of markdown files
|
||
as an ordered manuscript.
|
||
|
||
* **Left pane** — every `*.md` file in the workspace directory, in a manual order
|
||
you set by **dragging the `⠿` handle** up and down.
|
||
* **Right pane** — a markdown text editor for the selected file (optional live
|
||
preview via the *Preview* checkbox).
|
||
* **Order + contents are saved and version-controlled with git.** The order lives
|
||
in `order.json` inside the workspace, so it syncs along with the files.
|
||
* **Export** the whole manuscript as a single concatenated `.odt` file, with a
|
||
chapter heading before each file's content.
|
||
|
||
Built in Rust with [`egui`](https://github.com/emilk/egui)/`eframe`. The ODT
|
||
writer is native (no `pandoc`/LibreOffice needed at runtime).
|
||
|
||
## Build
|
||
|
||
```sh
|
||
cargo build --release
|
||
# binary: target/release/md-manuscript
|
||
```
|
||
|
||
Requires a Rust toolchain. The GUI needs a normal desktop session (X11 or
|
||
Wayland) with OpenGL — the usual runtime libraries on Debian:
|
||
|
||
```sh
|
||
sudo apt install libgl1 libxkbcommon0 libwayland-client0 libx11-6
|
||
```
|
||
|
||
(Only needed to *run* the GUI; building does not require them.)
|
||
|
||
## Install
|
||
|
||
```sh
|
||
install -Dm755 target/release/md-manuscript ~/.local/bin/md-manuscript
|
||
```
|
||
|
||
Optionally add a desktop launcher at
|
||
`~/.local/share/applications/md-manuscript.desktop`:
|
||
|
||
```ini
|
||
[Desktop Entry]
|
||
Type=Application
|
||
Name=md-manuscript
|
||
Exec=md-manuscript
|
||
Categories=Office;TextEditor;
|
||
Terminal=false
|
||
```
|
||
|
||
## Use
|
||
|
||
1. Set the **Workspace** path in the top bar (default: `~/Manuscript`) — type it,
|
||
or click **📂** to pick a folder in a native file browser — and press **Open**.
|
||
The directory is created if it does not exist.
|
||
2. Press **Init git** once to make the workspace a git repository. To sync with
|
||
another machine, add a remote yourself:
|
||
```sh
|
||
cd ~/Manuscript
|
||
git remote add origin <url>
|
||
git push -u origin main
|
||
```
|
||
After that, the **⟳ Sync (git)** button commits all changes, `pull --rebase`s,
|
||
and pushes.
|
||
3. Create files with **＋ New**, edit on the right, `Ctrl+S` (or the Save button)
|
||
to write to disk. Drag the `⠿` handles to reorder.
|
||
4. Set the **Chapter title** for the open file if you want to override the
|
||
auto-derived one (the field shows the automatic title as a hint). Leaving it
|
||
blank falls back to a `# Title:` line, then the file's first level-1 heading
|
||
(`# ...`), then the file name. Titles are saved to `titles.json` and sync with
|
||
git.
|
||
5. Set the **Export** path (type it, or click **📂** to choose the `.odt` file in a
|
||
native save dialog) and press **Export ODT** to produce the concatenated
|
||
document. Each file becomes a chapter headed by its title, optionally followed
|
||
by a caption from its `# Slug:` line.
|
||
|
||
The status bar shows a live **word count** for the current file, plus the net
|
||
words added (or removed) to it since the current session started. The count
|
||
updates as you type, including unsaved edits.
|
||
|
||
## Header stripping on export
|
||
|
||
Manuscript files often carry editorial notes and metadata above the prose that
|
||
should not appear in the finished document. On export, each file is cleaned up:
|
||
|
||
* **HTML comments** (`<!-- ... -->`, including multi-line ones) are removed.
|
||
* **The header block** — everything above the **Draft marker** line (set in the
|
||
top bar; default `### Rough Draft:`) — is dropped. From that header:
|
||
* `# Title:` becomes the chapter heading (unless a manual override is set), and
|
||
* `# Slug:` becomes an italic caption printed beneath the heading.
|
||
|
||
Any other header text is discarded. Files with no marker line are exported
|
||
whole, but stray `# Title:` / `# Slug:` lines are still lifted out. Clear the
|
||
Draft marker field to disable header splitting entirely.
|
||
|
||
For example, this source file:
|
||
|
||
```markdown
|
||
# Title: The Gate
|
||
# Slug: in which the door will not open
|
||
<!-- remember to foreshadow the key -->
|
||
outline: she arrives, she knocks, nothing
|
||
|
||
### Rough Draft:
|
||
|
||
The prose that actually gets exported begins here.
|
||
```
|
||
|
||
exports as a chapter titled **The Gate**, captioned *in which the door will not
|
||
open*, containing only the prose below the marker.
|
||
|
||
## Files the app writes
|
||
|
||
| Location | Purpose |
|
||
|---|---|
|
||
| `<workspace>/*.md` | your manuscript files |
|
||
| `<workspace>/order.json` | the manual ordering (committed to git) |
|
||
| `<workspace>/titles.json` | chapter-title overrides (committed to git) |
|
||
| `~/.config/md-manuscript/config.json` | last workspace, export path, prefs |
|
||
|
||
## Markdown supported in ODT export
|
||
|
||
Headings, paragraphs, **bold**, *italic*, ***both***, `inline code`, fenced/indented
|
||
code blocks (monospace, whitespace preserved), ~~strikethrough~~, ordered and
|
||
unordered (nested) lists, block quotes, horizontal rules, and links. Images are
|
||
rendered as a text placeholder (not embedded).
|