Usage guide

# Interactive login writes the API key to local config
somark login

# You can also set, read, and inspect config directly
somark config set api_key sk-your-api-key
somark config get api_key
somark config list

# For temporary use, environment variables are lighter
export SOMARK_API_KEY=sk-your-api-key

import warnings
from somark import SoMark, SoMarkWarning

# If you do not want Python programs to display SoMark warnings, filter them with warnings
warnings.filterwarnings("ignore", category=SoMarkWarning)

client = SoMark(api_key="sk-your-api-key")
response = client.parser.parse(file="./document.pdf")

print(response.warnings)  # list[str]

# One format without --out: writes to stdout, useful for pipes and scripts
somark parse ./document.pdf --formats md

# Quiet mode: hide SoMark warning output
somark --no-warnings parse ./document.pdf --formats md

# One format to a specific file; the parent directory must already exist
somark parse ./document.pdf --formats md --out ./document.md

# Multiple formats must go to an existing directory; creates parsed/document.md and parsed/document.json
mkdir -p ./parsed
somark parse ./document.pdf --formats md,json --out ./parsed/

# Separate multiple files with spaces; the batch output directory must also exist first
mkdir -p ./parsed
somark parse ./a.pdf ./b.pdf --out ./parsed/

# You can also read from a list file, one file path per line
mkdir -p ./parsed
somark parse --file-list ./files.txt --out ./parsed/

# Output Markdown with title-level recognition and HTML tables enabled
somark parse ./paper.pdf --formats md --title-levels --table-fmt html

# 1. Submit a task and only get task_id; do not wait for the result
somark parse ./large.pdf --async --formats md,json

# Submit multiple files at once; each file gets its own task_id
somark parse ./a.pdf ./b.pdf --async --formats md

# You can also read from a list file
somark parse --file-list ./files.txt --async --formats md

# 2. Wait for an existing task to finish and save the result locally
somark parse --task-id task_xxx --wait --out ./large.md

# 3. Query status once without blocking
somark parse --task-id task_xxx

# Table output is the default and works well for humans
somark usage

# JSON is better for scripts
somark usage --format json

# text is lighter for logs
somark usage --format text

# Preview a SoMarkDown file and open the browser automatically
somark preview ./document.smd

# Set the local service host and port
somark preview ./document.md --host 127.0.0.1 --port 7878

# Start only the service, without opening the browser
somark preview --no-open

# Convert every page of a PDF to images in the current directory
somark pdf toimg ./document.pdf

# Set output directory and resolution
somark pdf toimg ./document.pdf --out ./pages --dpi 200

# Customize image filenames
somark pdf toimg ./document.pdf --format "{name}-{n}.png"