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").

1. 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.

1. 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).