Skip to content
Documentation
Pushing Documents

Pushing Documents

The push command uploads markdown files to your Outline wiki.

Basic Usage 

# Push a single file
outline push --path ./deploy.md --collection-id "Engineering"

# Push a directory tree
outline push --path ./docs/ --collection-id "Engineering"

# Auto-create collection if it doesn't exist
outline push --path ./docs/ --collection-id "New Collection" --create-collection

Flags

FlagDefaultDescription
-p, --path.Path to markdown file or directory
--collection-id—Target collection (name, slug, or UUID)
--publishtruePublish created documents
--create-collectionfalseCreate collection if it doesn’t exist

Upsert Behavior

push is idempotent. It searches for an existing document by title:

  • Found → updates the content
  • Not found → creates a new document

This means you can run push repeatedly (e.g., in CI) without creating duplicates.

Collection Resolution

The --collection-id flag accepts:

  • Collection name: "Engineering"
  • Collection slug: engineering
  • URL ID: engineering-abc123
  • UUID: 550e8400-e29b-41d4-a716-446655440000

Image Upload

Local image references are automatically uploaded:

![architecture diagram](./images/arch.png)

Becomes an Outline attachment with the URL rewritten in the pushed document.

What Gets Pushed

When pushing a directory:

  • All .md files are included (recursive)
  • Non-markdown files are ignored (except images referenced in markdown)
  • Hidden files/directories (.git, .DS_Store) are skipped
  • Sort order: shallower files first, then index.md/README.md first, then alphabetical
ConfigurationDirectory Structure