Working with Assets

Learn how to manage images and files alongside your documentation using the CLI.

Supported formats

Images — png, jpg, jpeg, gif, webp, svg

Documents — pdf

Text — txt, log, csv, md

Data — json, xml, yaml, yml

File type matching is case-insensitive. Files with unsupported extensions are silently skipped.

Add assets to documents

Reference images and files using standard Markdown syntax. Paths are resolved relative to the document’s location:

![Architecture diagram](./images/architecture.svg)

[Download the report](./files/quarterly-report.pdf)

Push assets

meldoc push handles assets automatically — it parses each document for image and link references, uploads new or changed files, and creates bindings between documents and their assets.

meldoc push

Skip asset upload with --no-assets if you only want to update document content:

meldoc push --no-assets

Pull assets

meldoc pull downloads referenced assets by default. Missing or changed files are fetched automatically.

# Default — download missing or changed assets
meldoc pull

# Skip asset download
meldoc pull --no-assets

# Re-download all assets, even if unchanged
meldoc pull --force-assets

Deduplication

The CLI uses SHA256 hashes to avoid redundant uploads. The same file referenced in multiple documents is uploaded once. Unchanged assets are skipped on subsequent pushes. Renaming a file without changing its content doesn’t trigger a re-upload.

Organize asset files

Keep assets in dedicated directories alongside your documentation:

docs/
├── getting-started.meldoc.md
├── api-guide.meldoc.md
├── images/
│   ├── dashboard.png
│   └── architecture.svg
└── files/
    ├── sample-config.json
    └── report.pdf

For nested documents, assets resolve relative to the document:

docs/
├── guide/
│   ├── intro.meldoc.md       # ![](./images/logo.png)
│   └── images/
│       └── logo.png
└── api/
    ├── reference.meldoc.md   # ![](../guide/images/logo.png)
    └── ...

Warnings

If an asset file doesn’t exist locally, the CLI prints a warning but still publishes the document:

WARN: Asset file not found, skipping: ./images/missing.png

During link checking you may also see WARN: Referenced file not found: ....

What’s next?

Workflow — Daily push, pull, and sync workflows.

Command Reference — All flags for push and pull.