{"id":45138660,"url":"https://github.com/madstone-tech/veve-cli","last_synced_at":"2026-02-20T00:15:02.452Z","repository":{"id":325520786,"uuid":"1101495313","full_name":"madstone-tech/veve-cli","owner":"madstone-tech","description":"Fast, themeable markdown-to-PDF converter built with Go https://github.com/madstone-tech/veve-cli","archived":false,"fork":false,"pushed_at":"2025-12-13T04:15:12.000Z","size":19642,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T17:36:52.651Z","etag":null,"topics":["cli","command-line-tool","converter","document-conversion","golang","markdown","pandoc","pdf","pdf-generation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/madstone-tech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T18:55:15.000Z","updated_at":"2025-12-13T04:15:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/madstone-tech/veve-cli","commit_stats":null,"previous_names":["madstone-tech/veve-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/madstone-tech/veve-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madstone-tech%2Fveve-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madstone-tech%2Fveve-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madstone-tech%2Fveve-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madstone-tech%2Fveve-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madstone-tech","download_url":"https://codeload.github.com/madstone-tech/veve-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madstone-tech%2Fveve-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29637398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line-tool","converter","document-conversion","golang","markdown","pandoc","pdf","pdf-generation"],"created_at":"2026-02-20T00:15:01.727Z","updated_at":"2026-02-20T00:15:02.445Z","avatar_url":"https://github.com/madstone-tech.png","language":"Go","readme":"# veve-cli - Markdown to PDF Converter with Theme Support\n\n[![CI](https://github.com/madstone-tech/veve-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/madstone-tech/veve-cli/actions/workflows/ci.yml)\n[![Release](https://github.com/madstone-tech/veve-cli/actions/workflows/release.yml/badge.svg)](https://github.com/madstone-tech/veve-cli/actions/workflows/release.yml)\n[![Go Version](https://img.shields.io/badge/go-1.25+-blue)](https://golang.org)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\nA fast, themeable markdown-to-PDF converter built with Go. Convert your markdown files to beautiful PDFs with built-in and custom themes. Perfect for documentation, reports, and technical writing.\n\n## Features\n\n- 📄 **Markdown to PDF** - Fast, reliable conversion via Pandoc\n- 🎨 **Theme Support** - 3 built-in themes (default, dark, academic) + unlimited custom themes\n- ⚙️ **Theme Management** - List, add, and remove themes via CLI\n- 📝 **Custom Themes** - Create themes in `~/.config/veve/themes/` with YAML metadata\n- 🌐 **Remote Images** - Automatically download and embed remote images from HTTP/HTTPS URLs\n- 🔀 **Unix Composability** - Full stdin/stdout support for piping and scripting\n- 🛠️ **Configuration** - TOML-based config with XDG Base Directory support\n- 🚀 **Cross-Platform** - macOS, Linux, Windows support\n- 🔧 **Pandoc Flexibility** - Configurable PDF engines and Pandoc options\n- 📦 **Shell Completions** - bash, zsh, and fish autocompletion support\n- 🌍 **Unicode \u0026 Emoji Support** - Automatic PDF engine selection for unicode content including emoji, CJK characters, math symbols, and diacritics\n\n## Installation\n\n### macOS (Homebrew - Recommended)\n\n```bash\nbrew tap madstone-tech/tap\nbrew install veve\n```\n\nShell completions are automatically installed with Homebrew.\n\n### Linux\n\n#### Download Pre-built Binary\n\n```bash\n# AMD64\ncurl -sL https://github.com/madstone-tech/veve-cli/releases/latest/download/veve_Linux_x86_64.tar.gz | tar xz\nsudo mv veve /usr/local/bin/\n\n# ARM64\ncurl -sL https://github.com/madstone-tech/veve-cli/releases/latest/download/veve_Linux_arm64.tar.gz | tar xz\nsudo mv veve /usr/local/bin/\n```\n\n#### From Package Managers\n\n```bash\n# Debian/Ubuntu (when available)\nsudo apt install veve\n\n# Fedora (when available)\nsudo dnf install veve\n```\n\n### Windows\n\nDownload the latest `.zip` file from [releases](https://github.com/madstone-tech/veve-cli/releases/latest), extract it, and add the folder to your PATH.\n\n### From Go\n\n```bash\n# Latest version\ngo install github.com/madstone-tech/veve-cli/cmd/veve@latest\n\n# Specific version\ngo install github.com/madstone-tech/veve-cli/cmd/veve@v0.1.0\n```\n\n## Quick Start\n\n### Basic Conversion\n\n```bash\n# Convert markdown to PDF\nveve input.md -o output.pdf\n\n# Use default output name (input.pdf)\nveve input.md\n```\n\n### Theme Selection\n\n```bash\n# List all available themes\nveve theme list\n\n# Convert with a specific theme\nveve input.md --theme dark -o output.pdf\nveve input.md --theme academic -o output.pdf\n```\n\n### Remote Images\n\n```bash\n# Automatically download and embed remote images (enabled by default)\nveve input.md -o output.pdf\n\n# Explicit enable\nveve input.md --enable-remote-images=true -o output.pdf\n\n# Disable remote image downloading\nveve input.md --enable-remote-images=false -o output.pdf\n\n# Customize timeout and retries for unreliable networks\nveve input.md \\\n  --remote-images-timeout=30 \\\n  --remote-images-max-retries=5 \\\n  -o output.pdf\n\n# Use custom temp directory for downloads\nveve input.md \\\n  --remote-images-temp-dir=/mnt/fast-storage \\\n  -o output.pdf\n```\n\n### Unicode \u0026 Emoji Support\n\nveve automatically detects and renders unicode content including emoji, CJK characters, mathematical symbols, and diacritics. The tool selects an appropriate PDF engine based on system availability.\n\n#### Supported Unicode Content\n\n- **Emoji**: 🎉 📄 ✅ 🚀 ❤️ (standard emoji sets and ZWJ sequences like 👨‍💻)\n- **CJK Characters**: 世界 日本 中国 (Chinese, Japanese, Korean)\n- **Mathematical Symbols**: ∑ ± ∫ ∈ ∪ ∩ (and others)\n- **Diacritics**: Café naïve Zürich (combining marks and accents)\n- **Special Characters**: © ® ™ € £ ¥ § ¶ † ‡\n\n#### Basic Unicode Conversion\n\n```bash\n# Automatic engine selection for unicode content\nveve unicode-document.md -o output.pdf\n\n# Content with emoji 🎉, CJK 世界, math ∑, diacritics é automatically rendered\n```\n\n#### Explicit Engine Selection\n\n```bash\n# Use specific unicode-capable engine\nveve document.md --engine xelatex -o output.pdf\nveve document.md --engine weasyprint -o output.pdf\n\n# Available engines: xelatex, lualatex, weasyprint, prince\n```\n\n#### PDF Engine Requirements\n\nveve requires a unicode-capable PDF engine. Engines are tested in this order:\n\n1. **xelatex** (recommended) - Fast, widely available, excellent unicode support\n2. **lualatex** - Similar capabilities to xelatex\n3. **weasyprint** - Python-based, good unicode support\n4. **prince** - Commercial option with premium support\n\n#### Installation Requirements\n\n**macOS:**\n```bash\n# Install mactex (includes xelatex)\nbrew install mactex\n```\n\n**Ubuntu/Debian:**\n```bash\n# Option 1: xelatex\nsudo apt-get update\nsudo apt-get install texlive-xetex\n\n# Option 2: weasyprint\nsudo apt-get install weasyprint\n```\n\n**Fedora/RHEL:**\n```bash\n# Option 1: xelatex\nsudo dnf install texlive-xetex\n\n# Option 2: weasyprint\nsudo dnf install weasyprint\n```\n\n**Windows:**\n- Download [MiKTeX](https://miktex.org/) and select xelatex during installation\n- Or install weasyprint via pip: `pip install weasyprint`\n\n**Example Markdown:**\n\n```markdown\n# My Document\n\nHere's a remote image from a CDN:\n\n![Architecture Diagram](https://cdn.example.com/diagrams/architecture.png)\n\nAnd another from an external source:\n\n![Screenshot](https://docs.example.com/images/screenshot.png)\n\nLocal images still work too:\n\n![Local Image](./local-image.png)\n```\n\n**Features:**\n- 📥 Automatic download and embedding of HTTP/HTTPS image URLs\n- ⚡ Concurrent downloads (5 images at a time by default)\n- 🔄 Automatic retry with exponential backoff for transient failures\n- 💾 Disk space limits (500MB per session, 100MB per image)\n- 🧹 Automatic cleanup of temporary files\n- ✅ Graceful degradation if some images fail to download\n- 📊 Detailed error messages for troubleshooting\n\n### Custom Themes\n\n```bash\n# Create custom theme directory\nmkdir -p ~/.config/veve/themes\n\n# Create a custom theme file\ncat \u003e ~/.config/veve/themes/mygreen.css \u003c\u003c 'EOF'\n---\nname: mygreen\nauthor: Your Name\ndescription: My green theme\nversion: 1.0.0\n---\nbody {\n  font-family: Georgia, serif;\n  color: darkgreen;\n}\nh1 {\n  color: forestgreen;\n  border-bottom: 2px solid darkgreen;\n}\nEOF\n\n# Use your custom theme\nveve input.md --theme mygreen -o output.pdf\n```\n\n### Theme Management\n\n```bash\n# List all themes (built-in + custom)\nveve theme list\n\n# Install a theme from file\nveve theme add mytheme /path/to/mytheme.css\n\n# Install a theme from URL\nveve theme add mytheme https://example.com/themes/mytheme.css\n\n# Remove a custom theme\nveve theme remove mytheme\n```\n\n### Batch Processing\n\n```bash\n# Convert all markdown files in current directory\nfor file in *.md; do\n  veve \"$file\" -o \"${file%.md}.pdf\"\ndone\n\n# With specific theme\nfor file in *.md; do\n  veve \"$file\" --theme dark -o \"${file%.md}.pdf\"\ndone\n```\n\n### Unix Piping\n\n```bash\n# Convert from stdin to stdout\ncat input.md | veve - -o output.pdf\n\n# Pipe to other commands\nveve input.md -o - | curl -F \"file=@-\" https://api.example.com/upload\n\n# Integration with other tools\npandoc-generated-md | veve - -o output.pdf\n```\n\n## Configuration\n\nveve uses TOML for configuration. Config files are loaded from:\n\n1. `~/.config/veve/veve.toml` (XDG Base Directory)\n2. Environment variables (override config file)\n\n### Example Configuration\n\n```toml\n# ~/.config/veve/veve.toml\n\n# Default theme to use if not specified\ndefault_theme = \"dark\"\n\n# Default PDF engine\npdf_engine = \"pdflatex\"\n\n# Quiet mode (suppress non-error output)\nquiet = false\n\n# Verbose mode (detailed output)\nverbose = false\n```\n\n### Environment Variables\n\n```bash\n# Override configuration via environment\nexport VEVE_DEFAULT_THEME=\"dark\"\nexport VEVE_PDF_ENGINE=\"xelatex\"\nexport VEVE_QUIET=\"false\"\nexport VEVE_VERBOSE=\"true\"\n```\n\n## Command Reference\n\n### Main Command\n\n```bash\nveve [input] [flags]\n```\n\n**Core Flags:**\n\n- `-o, --output string` - Output PDF file path (default: input filename with .pdf extension)\n- `-t, --theme string` - Theme to use for PDF styling (default: \"default\")\n- `-e, --pdf-engine string` - Pandoc PDF engine to use (default: \"pdflatex\")\n- `--quiet` - Suppress non-error output\n- `--verbose` - Enable verbose output\n- `-h, --help` - Show help message\n- `-v, --version` - Show version\n\n**Remote Images Flags:**\n\n- `-r, --enable-remote-images` - Download and embed remote images (default: true)\n- `--remote-images-timeout int` - Timeout in seconds per image download (default: 10)\n- `--remote-images-max-retries int` - Maximum retry attempts for failed downloads (default: 3)\n- `--remote-images-temp-dir string` - Custom temporary directory for downloads (default: system temp)\n\n### Theme Commands\n\n```bash\n# List themes\nveve theme list\n\n# Add theme from file or URL\nveve theme add \u003cname\u003e \u003cpath/url\u003e\n\n# Remove theme\nveve theme remove \u003cname\u003e\nveve theme remove \u003cname\u003e --force  # Skip confirmation\n```\n\n### Shell Completion\n\nveve provides shell completion for bash, zsh, and fish shells. Completions include support for:\n- Commands: `convert`, `theme`, `completion`\n- Flags: `--engine`, `--theme`, `--output`, etc.\n- Engine names: `xelatex`, `lualatex`, `weasyprint`, `prince`\n\n#### Quick Installation\n\nThe easiest way to install completions:\n\n```bash\n# Auto-detect your shell and install\n./scripts/install-completion.sh\n\n# Or specify the shell explicitly\n./scripts/install-completion.sh bash\n./scripts/install-completion.sh zsh\n./scripts/install-completion.sh fish\n```\n\n#### Manual Installation\n\nIf you prefer to install manually or the script doesn't work for you:\n\n**Bash:**\n```bash\n# Generate and save completion\nveve completion bash \u003e ~/.bash_completions/veve\n# Add to ~/.bashrc or ~/.bash_profile\nsource ~/.bash_completions/veve\n```\n\n**Zsh:**\n```bash\n# Create zsh completion directory\nmkdir -p ~/.zsh/completions\n# Generate completion\nveve completion zsh \u003e ~/.zsh/completions/_veve\n# Add to ~/.zshrc\nfpath=(~/.zsh/completions $fpath)\nautoload -U compinit \u0026\u0026 compinit\n```\n\n**Fish:**\n```bash\n# Create fish completions directory\nmkdir -p ~/.config/fish/completions\n# Generate completion\nveve completion fish \u003e ~/.config/fish/completions/veve.fish\n```\n\n#### Testing Completions\n\nAfter installation, reload your shell configuration:\n\n```bash\n# Bash/Fish\nsource ~/.bashrc\nsource ~/.config/fish/config.fish\n\n# Zsh\nsource ~/.zshrc\n```\n\nThen test by typing:\n```bash\nveve conver\u003cTAB\u003e        # Should complete to \"convert\"\nveve convert --engine \u003cTAB\u003e  # Should show available engines\n```\n\n## Theme Development\n\nCreate custom themes with CSS styling. See [THEME_DEVELOPMENT.md](docs/THEME_DEVELOPMENT.md) for detailed guide.\n\n### Basic Theme Structure\n\n```css\n---\nname: mytheme\nauthor: Your Name\ndescription: A custom theme\nversion: 1.0.0\n---\n\n/* CSS styling */\nbody {\n  font-family: Georgia, serif;\n  color: #333;\n}\n\nh1 {\n  color: #006699;\n  border-bottom: 3px solid #006699;\n}\n\ncode {\n  background-color: #f5f5f5;\n  padding: 2px 4px;\n  border-radius: 3px;\n}\n```\n\n### Theme Locations\n\n- **Built-in themes**: Embedded in binary\n- **User themes**: `~/.config/veve/themes/*.css`\n- **Local themes**: Any path via `--theme /path/to/theme.css`\n\n## Integration Examples\n\n### Documentation Generation\n\n```bash\n# Generate PDF from markdown documentation\nveve docs/guide.md -o guide.pdf --theme academic\n\n# Batch convert documentation\nfor doc in docs/*.md; do\n  veve \"$doc\" --theme academic -o \"${doc%.md}.pdf\"\ndone\n```\n\n### Static Site Generators\n\n```bash\n# Hugo integration in build script\nfor md in content/**/*.md; do\n  veve \"$md\" -o \"static/${md%.md}.pdf\"\ndone\n\n# Gatsby integration\nnpm run build \u0026\u0026 veve content/blog/*.md -o public/pdfs/\n```\n\n### CI/CD Pipelines\n\n```bash\n# GitHub Actions example\n- name: Generate PDFs\n  run: |\n    for file in docs/*.md; do\n      veve \"$file\" --theme default -o \"build/${file%.md}.pdf\"\n    done\n\n- name: Upload artifacts\n  uses: actions/upload-artifact@v4\n  with:\n    path: build/*.pdf\n```\n\n## Remote Images Guide\n\n### Quick Start\n\nRemote images are **enabled by default**. Just use remote image URLs in your markdown:\n\n```markdown\n![diagram](https://cdn.example.com/diagram.png)\n![photo](https://cdn.example.com/photo.jpg)\n```\n\nWhen you run `veve convert document.md`:\n1. Images are automatically downloaded\n2. Downloaded files are cached in temp directory\n3. Markdown is rewritten with local paths\n4. PDF is generated with embedded images\n5. Temp files are cleaned up\n\n### Performance Tips\n\n**For Fast Networks:**\n```bash\nveve document.md  # Defaults are optimal for typical networks\n```\n\n**For Slow Networks:**\n```bash\nveve document.md \\\n  --remote-images-timeout=30 \\\n  --remote-images-max-retries=5\n```\n\n**For Large Image Batches:**\n```bash\nveve document.md \\\n  --remote-images-temp-dir=/mnt/fast-ssd  # Use faster storage\n```\n\n### Troubleshooting Remote Images\n\n| Problem | Solution |\n|---------|----------|\n| Images not downloading | Feature is enabled by default. Check that URLs are correct |\n| Timeout errors | Increase timeout: `--remote-images-timeout=30` |\n| Rate limit errors (429) | Automatic retries handle this. Check image source |\n| 404 errors | Verify image URLs in markdown are correct |\n| Disk space exceeded | Reduce document size or split into multiple conversions |\n| Cleanup warnings | Use custom temp dir: `--remote-images-temp-dir=./temp` |\n\nFor more details, see [specs/002-remote-images/quickstart.md](specs/002-remote-images/quickstart.md).\n\n## Troubleshooting\n\n### Pandoc not found\n\n```\n[ERROR] pandoc: Pandoc is required but not installed or not in PATH\n```\n\n**Solution**: Install Pandoc:\n\n```bash\n# macOS\nbrew install pandoc\n\n# Linux (Debian/Ubuntu)\nsudo apt-get install pandoc\n\n# Linux (Fedora)\nsudo dnf install pandoc\n\n# Windows (Chocolatey)\nchoco install pandoc\n```\n\n### Theme not found\n\n```\n[ERROR] invalid theme 'mytheme': available themes are: [default dark academic]\n```\n\n**Solution**:\n\n1. Check theme file exists: `ls ~/.config/veve/themes/mytheme.css`\n2. Use correct theme name (without .css extension)\n3. Use full path for local themes: `veve input.md --theme /path/to/mytheme.css`\n\n### Encoding issues with special characters\n\n**Solution**: Ensure your markdown file is UTF-8 encoded:\n\n```bash\nfile -i input.md  # Check encoding\niconv -f utf-16 -t utf-8 input.md \u003e input_utf8.md  # Convert if needed\n```\n\n### PDF generation slow\n\n**Solution**:\n\n1. Use faster PDF engine: `--pdf-engine xelatex` (faster than pdflatex)\n2. Check Pandoc performance: `pandoc --version`\n3. Simplify CSS in theme (reduce complexity)\n\n## Building from Source\n\n### Prerequisites\n\n- Go 1.25 or later\n- Pandoc 2.18 or later\n- Git\n\n### Build\n\n```bash\n# Clone repository\ngit clone https://github.com/madstone-tech/veve-cli.git\ncd veve-cli\n\n# Build\ngo build -o veve ./cmd/veve\n\n# Install to system\nsudo mv veve /usr/local/bin/\n\n# Verify\nveve --version\n```\n\n### Development\n\nThis project uses [Task](https://taskfile.dev/) to streamline common development workflows. Install Task if you haven't already:\n\n```bash\n# macOS\nbrew install go-task/tap/go-task\n\n# Linux\nsh -c \"$(curl --location https://taskfile.dev/install.sh)\" -- -d\n\n# Or via Go\ngo install github.com/go-task/task/v3/cmd/task@latest\n```\n\nThen use Task for common operations:\n\n```bash\n# Setup development environment\ntask dev-setup\n\n# Run tests\ntask test                 # All tests with race detector\ntask test-unit            # Unit tests only\ntask test-contract        # Contract tests only\ntask test-coverage        # Tests with coverage report\n\n# Code quality\ntask fmt                  # Format with gofmt\ntask lint                 # Run linter\ntask precommit            # Run all pre-commit checks\n\n# Build and install\ntask build                # Build binary\ntask install              # Build and install to /usr/local/bin\ntask uninstall            # Remove installation\n\n# See all available tasks\ntask --list-all\n```\n\nFor detailed information, see [TASKFILE_GUIDE.md](TASKFILE_GUIDE.md).\n\nTraditional Go commands still work:\n\n```bash\n# Run tests directly\ngo test ./...\n\n# Run with coverage\ngo test -cover ./...\n\n# Generate completions\n./scripts/generate-completions.sh\n\n# Install completions\n./scripts/install-completion.sh\n```\n\n## Contributing\n\nContributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\n# Clone and setup\ngit clone https://github.com/madstone-tech/veve-cli.git\ncd veve-cli\n\n# Install dependencies\ngo mod download\n\n# Run tests\ngo test -v ./...\n\n# Run linter\ngolangci-lint run ./...\n```\n\n## Release Process\n\nSee [docs/RELEASE.md](docs/RELEASE.md) for detailed release instructions.\n\nQuick version:\n\n```bash\n# Tag a release\ngit tag -a v0.2.0 -m \"Release v0.2.0\"\ngit push origin v0.2.0\n\n# GitHub Actions automatically builds and releases\n```\n\n## Documentation\n\n- [Remote Images Guide](specs/002-remote-images/quickstart.md) - Automatic image downloading and embedding\n- [Theme Development Guide](docs/THEME_DEVELOPMENT.md) - Create custom themes\n- [Integration Examples](docs/INTEGRATION.md) - Use veve in your workflow\n- [Release Guide](docs/RELEASE.md) - Create releases\n- [Contributing Guide](CONTRIBUTING.md) - Development guidelines\n\n## Performance\n\n### Conversion Performance\n\nTypical conversion times (Pandoc + PDF generation):\n\n| Task                          | Time         |\n| ----------------------------- | ------------ |\n| Simple document (\u003c 10 pages)  | \u003c 2 seconds  |\n| Complex document (\u003c 50 pages) | 2-5 seconds  |\n| Large document (\u003e 50 pages)   | 5-10 seconds |\n\n_Times vary based on Pandoc, PDF engine, and system performance_\n\n### Remote Image Download Performance\n\nWhen remote images are included:\n\n| Scenario | Time |\n|----------|------|\n| Single image (2MB) | ~2 seconds |\n| 5 images (10MB total) | ~2-3 seconds |\n| 20 images (40MB total) | ~10 seconds |\n\n_With 5 concurrent downloads (default). Times depend on network speed and image source responsiveness._\n\n**Performance Tips:**\n- Concurrent downloads (5 workers) provide ~2.5x speedup vs sequential\n- Images are cached during conversion (no re-downloads for duplicates)\n- Slow images don't block others (concurrent downloads continue)\n- Timeouts prevent hanging on unresponsive sources (default 10s, configurable)\n\n## Compatibility\n\n### Operating Systems\n\n- ✅ macOS (10.15+)\n- ✅ Linux (Ubuntu 18.04+, Fedora 30+, etc.)\n- ✅ Windows (10+)\n\n### Go Versions\n\n- ✅ Go 1.20+\n- ✅ Go 1.21+\n\n### Pandoc Versions\n\n- ✅ Pandoc 2.18+\n- ✅ Pandoc 2.19+\n- ✅ Pandoc 3.x+\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details\n\n## Acknowledgments\n\n- Built with [Cobra](https://github.com/spf13/cobra) for CLI\n- Configuration with [Viper](https://github.com/spf13/viper)\n- Conversion powered by [Pandoc](https://pandoc.org)\n- Inspiration from [Marked 2](https://marked2app.com)\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/madstone-tech/veve-cli/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/madstone-tech/veve-cli/discussions)\n- **Documentation**: See `/docs` directory\n\n## Changelog\n\n### v0.2.0 (December 2025)\n- ✨ **New Feature**: Automatic remote image downloading and embedding\n  - Downloads HTTP/HTTPS images during conversion\n  - Concurrent downloads (5 workers default)\n  - Retry logic with exponential backoff\n  - Disk space limits (500MB per session, 100MB per image)\n  - Detailed error messages and logging\n  - Graceful degradation on network failures\n- 🔄 Improved error handling and reporting\n- 📚 Enhanced documentation and examples\n\n### v0.1.0 (November 2025)\n- Initial release\n- Markdown to PDF conversion\n- Theme support (built-in and custom)\n- Theme management CLI\n- Configuration support\n\n## Roadmap\n\n- [ ] Web UI for theme preview\n- [ ] Built-in theme marketplace\n- [ ] Docker image with Pandoc\n- [ ] Package managers (apt, rpm, brew, etc.)\n- [ ] Template variables (author, date, etc.)\n- [ ] PDF merge capability\n- [ ] Batch image download progress indicator\n- [ ] Image caching across multiple conversions\n\n---\n\n**Transform your documentation with veve-cli** 📄✨\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadstone-tech%2Fveve-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadstone-tech%2Fveve-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadstone-tech%2Fveve-cli/lists"}