/
Documentation

Advanced Usage

Advanced Meldoc CLI capabilities: automation, debugging, and security.

Automation

Pre-commit Hook

Automatic documentation publishing before each commit.

Create .git/hooks/pre-commit:

#!/bin/bash

echo "Syncing documentation..."

if ! command -v meldoc &> /dev/null; then
    echo "meldoc not found, skipping"
    exit 0
fi

if [ -f ".env" ]; then
    source .env
fi

if meldoc scan 2>&1 | grep -q "changes"; then
    echo "Publishing documentation changes..."
    meldoc push --token $MELDOC_TOKEN
fi

Make it executable:

chmod +x .git/hooks/pre-commit

Post-merge Hook

Automatic documentation update after merge.

Create .git/hooks/post-merge:

#!/bin/bash

echo "Pulling documentation..."

if ! command -v meldoc &> /dev/null; then
    exit 0
fi

if [ -f ".env" ]; then
    source .env
fi

meldoc pull --token $MELDOC_TOKEN --force

Makefile

Add to your Makefile:

.PHONY: docs-sync docs-pull docs-scan

# Then `docs-pull` fetches and `docs-sync` publishes.
docs-sync: docs-scan
 meldoc push --token $(MELDOC_TOKEN)

docs-pull:
 meldoc pull --token $(MELDOC_TOKEN)

docs-scan:
 meldoc scan

Then docs-pull fetches and docs-sync publishes — run either with make. They are targets in your repository, not Meldoc’s.

Incremental cron pull (--updated-since)

For large repos that pull on a cron schedule, fetch only docs that changed since the previous run. The cutoff is an RFC3339 timestamp; the server returns content only for docs whose updated_at is strictly after the cutoff. Older docs come back as unchanged (alias only, no content).

A typical nightly job records the start time before running so the next invocation can pick up everything that landed during or after this run:

SINCE_FILE=.meldoc/last-pull-utc
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
SINCE=$(cat "$SINCE_FILE" 2>/dev/null || true)

if [ -n "$SINCE" ]; then
 meldoc pull --token "$MELDOC_TOKEN" --local --yes --updated-since "$SINCE"
else
 meldoc pull --token "$MELDOC_TOKEN" --local --yes
fi

echo "$NOW" > "$SINCE_FILE"

Combined with --local/--tracked, this is the recommended pattern for daily syncs on repos with many documents — the request is also chunked automatically by Manifest.MaxBatchSize.

Debugging

Debug Mode

Add --debug to any command:

meldoc scan --debug
meldoc push --token your-token --debug
meldoc pull --token your-token --debug

Checking State

View internal state:

# Configuration
cat meldoc.config.yml

# Sync cache
cat .meldoc/cache/state.json

# Sync position
cat .meldoc/cache/cursor.json

# Conflicts
ls -la .meldoc/conflicts/

Clearing Cache

If cache is corrupted:

rm -rf .meldoc/cache/state.json .meldoc/cache/cursor.json
meldoc scan

Network Check

curl -v https://api.meldoc.io/health

Security

Protecting Your Token

Never commit your token to the repository!

Use environment variables:

export MELDOC_TOKEN="your-token"

Or a .env file (add to .gitignore):

echo "MELDOC_TOKEN=your-token" > .env
echo ".env" >> .gitignore

File Permissions

Set secure permissions on files:

chmod 600 .env
chmod 600 meldoc.config.yml

Different Tokens for Environments

# Development
export MELDOC_TOKEN_DEV="dev-token"

# Production
export MELDOC_TOKEN_PROD="prod-token"

# Usage
if [ "$ENV" = "production" ]; then
    meldoc push --token $MELDOC_TOKEN_PROD
else
    meldoc push --token $MELDOC_TOKEN_DEV
fi

IDE Integration

VS Code

Create .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Meldoc: Publish",
      "type": "shell",
      "command": "meldoc push --token ${env:MELDOC_TOKEN}",
      "group": "build"
    },
    {
      "label": "Meldoc: Pull",
      "type": "shell",
      "command": "meldoc pull --token ${env:MELDOC_TOKEN}",
      "group": "build"
    },
    {
      "label": "Meldoc: Scan",
      "type": "shell",
      "command": "meldoc scan",
      "group": "build"
    }
  ]
}

Create .vscode/settings.json:

{
  "files.associations": {
    "*.meldoc.md": "markdown"
  }
}

See also: