#+TITLE: El Prisma
[[https://github.com/agzam/prisma.el/actions/workflows/run-tests.yml][https://github.com/agzam/prisma.el/actions/workflows/run-tests.yml/badge.svg]]

Same content, different spectrum.

* Status: experimentally stable
*This is a somewhat experimental unit, use at your own discretion and risk.* Things may change drastically, or I may decide to scrap the entire idea and re-implement it differently. Personally, I've been using it very successfully, but I'd still advise caution when editing large and very important documents; I cannot guarantee that changing something in one place won't inexplicably move things around in some other parts of the document. This is a fundamentally very difficult problem to solve deterministically - structural diffing of dissimilar formats. Add to this the various, different flavors of markdown and voila! Now you have a jumble.

* Seamless conversion and editing

Open a Markdown file, run =prisma-convert=, and you're editing in Org mode. Rearrange headings with =org-metaup=, restructure lists, refactor content - use the full power of Org. When done, =C-c C-c= commits your changes back. The source Markdown updates surgically: only the regions you touched change, everything else stays byte-identical.

Works the other way too - convert Org to Markdown when you need GitHub-flavored output.

Currently supported: Markdown (GFM) <-> Org

* How it works

Prisma builds a render map during conversion that tracks which source AST node produced which region of mirror text. On commit, it text-diffs the mirror (before vs after your edits), identifies the affected source nodes, re-parses just those regions, and patches them back. Unchanged regions - tables, code blocks, links, metadata - pass through untouched.

This is not Pandoc. There is no whole-document re-serialization, no normalization, no lost formatting. Format-specific constructs with no target equivalent pass through as literal text and round-trip verbatim.

* Usage

#+begin_src emacs-lisp
;; In a Markdown buffer:
M-x prisma-convert       ; opens Org mirror, cursor on same heading

;; Edit freely - rearrange, refactor, restructure:
C-c C-c                  ; commit changes back to source
C-c C-k                  ; cancel, discard mirror
C-c C-p C-d              ; preview diff before committing
#+end_src

Region conversion: select a region before converting to work on just a section.

* Copying between formats

#+begin_src emacs-lisp
(prisma-yank-mode 1)
#+end_src

A kill remembers the markup format of the buffer it came from. Paste it into a buffer of the other format and it arrives converted - Markdown copied into an Org buffer lands as Org, Org copied into a Markdown buffer lands as Markdown. Kills from anywhere else, and pastes into anything but Org and Markdown, are untouched.

It works on the kill ring itself, so =yank=, =yank-pop= and Evil's =p= and =P= all go through it. A bare =C-u= before the paste inserts the kill unchanged; so does binding =prisma-yank-inhibit= around a paste. If conversion fails, the kill is pasted as-is and the error goes to the echo area.

* Prerequisites

Emacs 29.1+ with tree-sitter support. Compiled grammars for =markdown= and =markdown-inline= (from [[https://github.com/tree-sitter-grammars/tree-sitter-markdown][tree-sitter-grammars/tree-sitter-markdown]]).

Missing grammars are reported with a clear error; =M-x prisma-md-install-grammars= builds and installs both (requires git and a C compiler). Note that grammar libraries are tied to the Emacs tree-sitter ABI - after a major Emacs upgrade you may need to run it again.

* License

GPL-3.0-or-later