Getting Started

Prerequisites

Required

• Python 3.11-3.13 - Required runtime (3.14 not yet supported due to onnxruntime)
• uv - Package manager (recommended)

Optional Dependencies

These are required for specific features:

Dependency	Required For	Installation
Playwright	--playwright (SPA rendering)	Package auto-installed, browser requires uv run playwright install chromium
FFmpeg	Audio/video processing	apt install ffmpeg (Linux) / brew install ffmpeg (macOS)
Jina API Key	--jina (URL conversion)	Set JINA_API_KEY env var
LLM API Key	--llm (AI enhancement)	Set OPENAI_API_KEY or provider-specific key. Subscription providers (chatgpt/, gemini-cli/, claude-agent/, copilot/) use CLI/OAuth auth instead
Cloudflare	--cloudflare (cloud rendering & conversion)	Set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID env vars

Browser Automation

For SPA websites (Twitter, React apps, etc.), Playwright is used automatically. Before first use, install the browser:

uv run playwright install chromium
# Linux also requires system dependencies:
uv run playwright install-deps chromium

Then use --playwright flag to force browser rendering.

Installation

One-Click Setup (Recommended)

Run the setup script to automatically install Python, UV, and markitai:

Linux/macOS

curl -fsSL https://raw.githubusercontent.com/Ynewtime/markitai/main/scripts/setup.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Ynewtime/markitai/main/scripts/setup.ps1 | iex"

Security Notice

• The script will warn you if running as root/Administrator
• All installations require explicit confirmation (default: No)
• Remote script execution requires two-step confirmation

The script will:

• Check for Python 3.11-3.13
• Install uv package manager (requires confirmation)
• Install markitai with all optional dependencies

Version Pinning

Pin specific versions using environment variables:

Linux/macOS

export MARKITAI_VERSION="0.11.2"
export UV_VERSION="0.9.27"
curl -fsSL https://raw.githubusercontent.com/Ynewtime/markitai/main/scripts/setup.sh | sh

Windows

$env:MARKITAI_VERSION = "0.10.0"
$env:UV_VERSION = "0.9.27"
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Ynewtime/markitai/main/scripts/setup.ps1 | iex"

Manual Installation

# Using uv (recommended)
uv tool install markitai

# Or using uv pip (for virtual environment)
uv pip install markitai

Quick Start

First Run

For new users, the interactive mode guides you through initial setup:

markitai -I

Or initialize configuration with the setup wizard:

# Interactive setup wizard
markitai init

# Quick mode (generate default config)
markitai init --yes

Basic Conversion

Convert a single document to Markdown:

markitai document.docx

Without -o, this prints the output to stdout. With -o, it saves to the specified directory:

markitai document.docx -o output/

URL Conversion

Convert web pages directly:

markitai https://example.com/article -o output/

LLM Enhancement

Enable AI-powered format cleaning and optimization:

markitai document.docx --llm

This requires setting up an API key (see Configuration).

Using Presets

Markitai provides three presets for common use cases:

# Rich: LLM + alt text + descriptions + screenshots
markitai document.pdf --preset rich

# Standard: LLM + alt text + descriptions
markitai document.pdf --preset standard

# Minimal: Basic conversion only
markitai document.pdf --preset minimal

Batch Processing

Convert multiple files in a directory:

markitai ./docs -o ./output

Resume interrupted batch processing:

markitai ./docs -o ./output --resume

System Check

Verify all dependencies and auto-fix missing components:

# Check system health
markitai doctor

# Auto-fix missing components
markitai doctor --fix

Output Structure

output/
├── document.docx.md        # Basic Markdown (skipped in --llm mode unless --keep-base)
├── document.docx.llm.md    # LLM-enhanced version (when --llm is used)
├── .markitai/               # Metadata namespace
│   ├── assets/
│   │   ├── document.docx.0001.jpg
│   │   └── images.json     # Image descriptions
│   ├── screenshots/         # Page screenshots (when --screenshot is used)
│   │   └── document.docx.0001.png
│   ├── reports/             # Conversion reports (JSON)
│   └── states/              # Batch state files (for --resume)

TIP

In --llm mode, only .llm.md is written by default. Use --keep-base to also write the base .md file.

Supported Formats

Format	Extensions
Word	.docx, .doc
PowerPoint	.pptx, .ppt
Excel	.xlsx, .xls
PDF	.pdf
Text	.txt, .md, .markdown
Images	.jpg, .jpeg, .png, .webp
URLs	http://, https://

Platform-Specific Features

Some features have platform-specific behavior or limitations:

Windows

Feature	Support	Notes
Legacy Office (.doc, .xls, .ppt)	✅ Full	Uses COM automation
PPTX Slide Rendering	✅ Full	MS Office preferred, LibreOffice fallback
EMF/WMF Images	✅ Full	Native support
Browser Automation	✅ Full	Hidden window mode

Linux

Feature	Support	Notes
Legacy Office (.doc, .xls, .ppt)	✅ Full	Requires LibreOffice (Windows uses COM, LibreOffice as fallback)
PPTX Slide Rendering	✅ Full	Requires LibreOffice
EMF/WMF Images	❌ No	Windows-only format
Browser Automation	✅ Full	Requires system dependencies

Install LibreOffice:

# Ubuntu/Debian
sudo apt-get install libreoffice

# Fedora/RHEL
sudo dnf install libreoffice

Install Playwright browsers:

uv run playwright install chromium
uv run playwright install-deps chromium  # Install system dependencies

macOS

Feature	Support	Notes
Legacy Office (.doc, .xls, .ppt)	✅ Full	Requires LibreOffice
PPTX Slide Rendering	✅ Full	Requires LibreOffice
EMF/WMF Images	❌ No	Windows-only format
Browser Automation	✅ Full	-

Install LibreOffice:

brew install --cask libreoffice

Next Steps

• Configuration - Configure LLM providers and other settings
• CLI Reference - Full command reference