Edit a post by numbered blocks

Edit a post by numbered blocks

Use this instead of PATCH /posts/:id when the person wants to follow and steer an edit. You send only the blocks that change; the person watches a live page where every block has a number, says "rewrite 7" or "move 12 above 9", and approves at the end. This needs the edit mode feature (GET /features shows post_edit_mode); without it every call answers 403 feature_not_available, so use PATCH. Setup, keys and errors are in the Bloggo skill; this one only covers editing.

Start

POST /posts/:id/edit (any status, drafts too). The reply has edit.url, edit.revision and edit.blocks: every block with its number n and its markdown. Block 1 is the title, block 2 is the frontmatter if the post has one, then each paragraph, heading, whole list, code block, quote or table is one block, and an image with its italic caption line is one block. Give the person edit.url and say they can watch the changes there; the link only lets them look. Calling it again on an open edit returns the same work with a new link and the old link stops working.

The post itself does not change until you approve. Numbers are positions: they shift when blocks are inserted or deleted, and they are not part of the post.

Change blocks

POST /posts/:id/edit/commands with {"revision": N, "commands": [...]}, revision taken from your last reply. Commands apply in order, each seeing the result of the one before; if one fails nothing is applied.

• Replace a block: {"op":"edit","block":7,"markdown":"New text"}. Block 1 takes the new title.
• Insert: {"op":"insert","after":7,"markdown":"..."} (between 7 and 8), or "at":"start" or "at":"end". The text can be several blocks.
• Delete: {"op":"delete","block":7} or "block":"7-9".
• Swap two blocks or two ranges: {"op":"swap","a":7,"b":8}. Move block 7 down: swap 7 and 8. Move block 7 up: swap 6 and 7. Move block 12 above blocks 9 to 11: {"op":"swap","a":"9-11","b":12}.

The reply has changed (the touched blocks with their new numbers) and the new revision. Send only the blocks you change. If the numbers below an insert or delete moved, use the new ones. A 409 stale_edit means the numbers are out of date (the person or another caller undid something): GET /posts/:id/edit shows the current blocks and revision; look again before you resend. A 422 says why a command was refused; the title and frontmatter cannot be moved or deleted, and two lists in a row would merge into one block, so keep a paragraph between them.

Undo and redo

When the person says "undo that", send {"op":"undo"} as the only command in a call ("steps": 3 goes back three). {"op":"redo"} goes forward. Every step is kept as a tree: a new change after an undo starts another branch and the undone one stays. GET /posts/:id/edit/history lists the steps (step, parent, summary, current), and {"op":"undo","to":4} jumps to step 4 on any branch, so "go back to the version before I asked for the shorter intro" is a lookup in the history and one call. Tell the person which step you are on.

Approve

Only when the person says it looks right, call POST /posts/:id/edit/approve. It saves the post with the normal checks (size limit, content check) and publishes it, so a draft goes live; a published post is updated. If the post was changed another way after the edit started you get 409 post_changed: tell the person, and only send {"force": true} if they agree to replace that change. To drop the edit, DELETE /posts/:id/edit.

An edit that nobody changes for 24 hours expires. A blog can have 10 posts in edit at once.