Working with Outline

Markdown

• Mermaid diagrams need ```mermaidjs fences, NOT ```mermaid — the wrong fence silently renders as a plain code block.
• Otherwise standard markdown. Use ATX headings (#–######); they power the TOC and section tools.

Structure

• Collections contain documents; documents nest via parent_document_id. Browse: list_collections, get_collection_structure.
• Lifecycle: draft → published → archived → trash (30-day recovery via restore_document; delete_document(permanent=True) is unrecoverable).
• create_document(template=True) / update_document(template=True) adds to the "New from template" picker.
• Titles are not unique; resolve to IDs with get_document_id_from_title or search_documents. Check get_document_backlinks before restructuring or deleting.

Search defaults to published only

Drafts and archived docs are invisible to search_documents and list_recently_updated_documents unless widened: status_filter=["draft", "published", "archived"].

Reading large documents

1. get_document_toc — headings with 0-based line numbers.
2. read_document_section(heading=...) — case-insensitive substring; accepts headings as the TOC prints them (e.g. "## Background").
3. search_document_content(query=...) — grep within the document: matching lines with line numbers and context. Use it to locate text for edit_document old_strings or read_document offsets.
4. read_document(offset=N, limit=M) — TOC/grep line numbers are valid offsets.

Full read_document only for small documents.

Editing

• Default to edit_document: each old_string must match exactly once (add surrounding context to disambiguate); edits apply sequentially, all-or-nothing. Batch all edits for one document into a single call.
• update_document only for full replacement, title changes, or append=True (sends just the chunk).

Staged rewrites

edit_document(id, edits=[...], save=False)   # stage, repeat as needed
edit_document(id, edits=[...], save=True)    # final batch + push all
edit_document(id, edits=[], save=True)       # or: flush only

One API write total. Staged changes are server-memory only — flush before ending; a restart discards them. Read tools show staged text with an "unsaved changes" notice; export_document bypasses staging and returns the last saved content.

Many documents

Use batch_create_documents, batch_update_documents, batch_move_documents, batch_archive_documents, batch_delete_documents (10–50 per call; per-document results) instead of loops.

Missing tools

Deployments may be read-only, delete-disabled, or scope-filtered. Use what's listed; if an editing tool is absent, say so.

Exploration

For broad search-and-summarize, delegate to the outline-explorer agent (bundled with this plugin).