landon
507e0ab724
Each file is now cleaned before conversion: HTML comments are removed and everything above the configurable Draft marker (default "### Rough Draft:") is dropped. A "# Title:" line becomes the chapter heading and a "# Slug:" line becomes an italic caption beneath it. - new preprocess module (strip_comments + header parse) with tests - Chapter gains a slug rendered via a Chapter_20_Caption style, italic at both paragraph-style and character-run level - draft_marker config setting + top-bar field - export title priority: override > # Title: > first # heading > filename Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
122 lines
4.4 KiB
Markdown
122 lines
4.4 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`) 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 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:
|
||
|
||
```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).
|