| name | outline |
| description | Conventions and efficient workflows for Outline knowledge bases via mcp-outline tools. Use when creating, editing, restructuring, or diagramming Outline documents — covers Outline markdown quirks (mermaidjs code fences), document and collection structure, string-match editing, staged rewrites, batch operations, and search status filters. |
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
get_document_toc — headings with 0-based line numbers.read_document_section(heading=...) — case-insensitive substring;
accepts headings as the TOC prints them (e.g. "## Background").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.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).
