vortiago / outline

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 oldstrings or `readdocument` 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).