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/eframe. The ODT writer is native (no pandoc/LibreOffice needed at runtime).

Build

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:

sudo apt install libgl1 libxkbcommon0 libwayland-client0 libx11-6

(Only needed to run the GUI; building does not require them.)

Install

install -Dm755 target/release/md-manuscript ~/.local/bin/md-manuscript

Optionally add a desktop launcher at ~/.local/share/applications/md-manuscript.desktop:

[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) 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:

   cd ~/Manuscript
   git remote add origin <url>
   git push -u origin main
   

   After that, the ⟳ Sync (git) button commits all changes, pull --rebases, 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 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.

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:

# 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).