landon
6680c001bf
Every chapter after the first now starts on a new page via a Chapter_20_Break heading style (fo:break-before="page"); the first chapter keeps the plain heading so there is no blank leading page. Chapter titles now resolve as: manual override > "# Title:" header > the chapter's 1-based position in the left pane (e.g. "3."). The old "# heading" / filename fallbacks are replaced by this numbering, and the same logic drives the chapter-title hint. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
129 lines
4.9 KiB
Markdown
129 lines
4.9 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 in the header, and if there is none, to
|
||
the chapter's **position in the left pane** followed by a period (`1.`, `2.`,
|
||
…). 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. **Every chapter starts on a new page**
|
||
(the first chapter excepted, so there is no blank leading page).
|
||
|
||
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).
|