libreoffice-writer

LibreOffice Writer

Use the bundled writer modules for UNO-backed Writer document work. All paths must be absolute. Bundled modules live under scripts/ in this skill directory, so set PYTHONPATH=<skill_base_dir>/scripts. If setup or runtime issues appear, check references/troubleshooting.md.

API Surface

# Non-session utilities
create_document(path, source

Structured Targets: WriterTarget

Target kinds

Resolution rules

• Omit target to read the full document or append inserted content at the end.
• Use after and before to constrain a search window.
• Use occurrence when repeated text is expected; otherwise matching must be unique.
• Prefer full sentences or distinctive paragraph-sized phrases for text, after, and before anchors; single-word anchors are often too brittle for realistic prose edits.
• For table/image targets, prefer name; use index only when order is stable.
• For insertion after inline text, Writer inserts at the boundary after the matched span; paragraph breaks must come from the inserted text or the session helper.

Formatting Payload

Notes:

• Character and paragraph formatting can be combined in one call.
• Paragraph properties such as align apply to the full paragraph containing the match, not just the exact matched span.
• At least one formatting field must be set.

List Items

• level is zero-based nesting.
• Nesting cannot skip levels.
• ordered=True uses a numbering style; ordered=False uses bullets.

Metadata

• set_metadata() accepts a dictionary of key-value pairs.
• Supported keys are title, author, subject, keywords, and description.
• keywords may be a comma-separated string; get_metadata() returns them as one comma-separated string.

Patch DSL

Use patch() or session.patch() to apply ordered operations.

Supported operation types

• insert_text
• replace_text
• delete_text
• format_text
• insert_table
• update_table
• delete_table
• insert_image
• update_image
• delete_image
• insert_list
• replace_list
• delete_list

Patch value rules

• Use target.* fields for target definition.
• To append at the end of the document, omit all target.* fields; do not use a bare target.kind = insertion without anchors.
• Use format.* fields for formatting payloads.
• Use list.ordered plus JSON items for list operations.
• items and data must be valid JSON.
• Heredoc blocks are supported with <<TAG ... TAG for multiline text or JSON.

Modes

• atomic stops on first failure, resets the session, and persists nothing.
• best_effort keeps successful earlier operations and records failures.

PatchApplyResult fields:

• mode
• overall_status = "ok" | "partial" | "failed"
• operations = list of PatchOperationResult
• document_persisted

For standalone patch(path, ...), document_persisted means the changes were saved to disk. For session.patch(...), it means the patch produced successful mutations in the current open session state.

Example: Edit a Report in Session

Example: Patch an Existing Document

Snapshots

Use snapshots to verify layout after formatting, list edits, image placement, or table changes.

• Prefer session.export() while a document is already open in a WriterSession.
• Use standalone export_document() when exporting an existing file without keeping a session open.
• get_metadata() normalizes keywords into one comma-and-space separated string.

Common Mistakes

• Passing a relative path; UNO-facing Writer APIs expect absolute file paths.
• Omitting occurrence for repeated text and then getting an ambiguity error.
• Using anchors that are too short or too common; prefer full-sentence or paragraph-level anchor text plus after / before bounds when possible.
• Expecting align to apply only to a phrase; Writer applies paragraph alignment to the containing paragraph.
• Supplying malformed JSON in items or data patch fields.
• Forgetting to clean up captured snapshots after inspection.
• Calling session.export() or other methods after session.close().
• The Markdown filter for markdown import / export requires LibreOffice 26.2+.
• The "start" and "end" paragraph alignment options require LibreOffice 26.2+.