From 0afacd0d12feb134f12ecb952135b2de8dfb281f Mon Sep 17 00:00:00 2001 From: Anthony Stirling <77850077+Frooodle@users.noreply.github.com> Date: Wed, 1 Apr 2026 09:58:16 +0100 Subject: [PATCH] cleanup docs, remove outdated docs, remove invalid enteries --- docs/Configuration/Configuration.md | 12 +- docs/Functionality/Advanced-Tools.md | 323 +----- docs/Functionality/Compare.md | 404 +------ docs/Functionality/Compress.md | 353 +------ .../Content-Editing/Content-Editing.md | 67 +- docs/Functionality/Convert/Convert.md | 302 +----- docs/Functionality/Functionality.md | 46 +- docs/Functionality/Mobile-Scanner.md | 2 +- docs/Functionality/Multi-Tool.md | 431 +------- docs/Functionality/OCR.md | 301 +----- docs/Functionality/Read-and-Annotate.md | 490 +-------- docs/Functionality/Recommended-Tools.md | 214 +--- .../Security/Certificate-Signing.md | 995 ++++-------------- docs/Functionality/Security/Security.md | 52 - docs/Functionality/Security/Sign.md | 371 +------ docs/Functionality/The Technologies.md | 112 +- docs/Getting Started.md | 31 +- docs/Installation/Docker Install.md | 150 +-- docs/Paid-Offerings.md | 17 +- docs/Server-Admin-Onboarding.md | 7 +- 20 files changed, 590 insertions(+), 4090 deletions(-) diff --git a/docs/Configuration/Configuration.md b/docs/Configuration/Configuration.md index 53f4d0ad..5d5b2d13 100644 --- a/docs/Configuration/Configuration.md +++ b/docs/Configuration/Configuration.md @@ -138,12 +138,6 @@ To force a specific default language regardless of browser settings, users must > 💡 **Tip**: Set `SYSTEM_DEFAULTLOCALE` to your organization's primary language. Users can always override it using the language selector in the top-right corner. -### Deployment Mode - -```bash -MODE=BOTH # Options: BOTH, FRONTEND, BACKEND -``` - ### File Upload Limits @@ -182,13 +176,11 @@ For advanced features and specific use cases, see these detailed guides: ### Authentication & Security **[Single Sign-On (SSO)](./Single%20Sign-On%20Configuration.md)** -- OAuth2 (Google, GitHub, Keycloak, OIDC) - Enterprise only -- SAML2 (Okta, Azure AD) - Enterprise only +- OAuth2 (Google, GitHub, Keycloak, OIDC) - Server tier +- SAML2 (Okta, Azure AD) - Enterprise tier - Complete configuration examples **[System and Security](./System%20and%20Security.md)** -- Split deployment (frontend/backend separation) -- CORS configuration - Server certificates - JWT configuration diff --git a/docs/Functionality/Advanced-Tools.md b/docs/Functionality/Advanced-Tools.md index 2381cb2f..6682e0ba 100644 --- a/docs/Functionality/Advanced-Tools.md +++ b/docs/Functionality/Advanced-Tools.md @@ -7,7 +7,7 @@ description: Power user features for automation and complex PDF operations # Advanced Tools -Advanced tools for power users, automation workflows, and complex PDF operations. These tools provide enhanced capabilities beyond standard PDF manipulation. +Advanced tools for automation workflows and complex PDF operations. --- @@ -17,29 +17,9 @@ Advanced tools for power users, automation workflows, and complex PDF operations **Tool ID:** `automate` -Create sophisticated multi-step workflows that combine multiple PDF operations into automated sequences. +Chain multiple operations into automated workflows. Save and reuse pipeline configurations, process files automatically with predefined steps, and set up folder watching for automatic processing. -#### What it does -- Chain multiple operations into automated workflows -- Save and reuse pipeline configurations -- Process files automatically with predefined steps -- Support for folder watching and automatic processing -- JSON-based configuration for advanced users - -#### Perfect for -- Repetitive multi-step PDF processing -- Automated document workflows -- Batch processing with consistent steps -- Integration with folder scanning -- Team workflow standardization - -#### Example Workflows -- **Document Processing:** Split → Add watermark → Compress → Archive -- **Invoice Processing:** OCR → Extract pages → Add metadata → Save -- **Report Generation:** Merge → Add page numbers → Add stamp → Export -- **Bulk Conversion:** Convert → Compress → Add password → Organize - -**📖 [Read the complete Pipeline Automation Guide →](../Configuration/Pipeline.md)** for detailed examples, JSON configuration, folder scanning setup, and best practices. +**[Read the complete Pipeline Automation Guide →](../Configuration/Pipeline.md)** --- @@ -47,67 +27,23 @@ Create sophisticated multi-step workflows that combine multiple PDF operations i **Tool ID:** `autoRename` -Automatically rename PDF files based on their content analysis. - -#### What it does -- Analyze PDF content to determine appropriate filename -- Extract title, header, or prominent text -- Use largest font text as filename -- Batch rename multiple PDFs at once -- Configurable naming rules - -#### Perfect for -- Organizing scanned documents -- Renaming downloaded PDFs with generic names -- Batch organizing document libraries -- Creating descriptive filenames automatically - -#### How it works -1. Upload one or more PDFs -2. Algorithm analyzes each PDF for: - - Document title in metadata - - Largest font text (likely the header/title) - - First prominent text on page 1 -3. Suggests filename based on findings -4. Option to review and modify suggestions -5. Batch rename and download - -#### Naming Strategy -The tool uses this priority order: -1. **PDF Metadata Title** (if present and meaningful) -2. **Largest Font Text** on first page -3. **First Heading** or prominent text -4. **First Line** of readable text - -#### Tips -- Works best with documents that have clear titles -- Scanned documents may need OCR first for better results -- Review suggestions before batch renaming -- Combine with OCR for scanned documents +Automatically rename PDF files based on their content. Analyzes each PDF and suggests filenames using this priority: +1. PDF metadata title (if present) +2. Largest font text on first page +3. First heading or prominent text +4. First line of readable text + +Works best with documents that have clear titles. Scanned documents may need [OCR](./OCR.md) first. --- -## Advanced Formatting Tools +## Formatting Tools ### Adjust Contrast **Tool ID:** `adjustContrast` -Fine-tune brightness, contrast, and saturation of PDF content. - -#### What it does -- Adjust brightness levels -- Modify contrast for better readability -- Change saturation (color intensity) -- Apply adjustments to all pages or specific ranges -- Preview changes before applying - -#### Perfect for -- Improving readability of faded scans -- Enhancing poor quality scanned documents -- Adjusting over/under-exposed photos in PDFs -- Creating high-contrast versions for accessibility -- Fixing washed-out images +Adjust brightness, contrast, and saturation of PDF content. Useful for improving readability of faded scans or creating high-contrast versions. --- @@ -115,34 +51,9 @@ Fine-tune brightness, contrast, and saturation of PDF content. **Tool ID:** `repair` -Attempt to repair corrupted or damaged PDF files. - -#### What it does -- Fix structural PDF errors -- Recover content from damaged files -- Repair broken PDF streams -- Reconstruct missing elements -- Salvage readable content from corrupted PDFs - -#### Perfect for -- Opening PDFs that won't load -- Recovering important documents -- Fixing corrupted downloads -- Repairing files from failing storage -- Salvaging partially damaged files - -#### What it can fix -- Broken cross-reference tables -- Corrupted object streams -- Missing or damaged headers -- Truncated files -- Encoding errors - -#### Limitations -- Cannot recover physically deleted data -- May not work with heavily encrypted files -- Success depends on extent of corruption -- Some formatting may be lost in recovery +Attempt to repair corrupted or damaged PDF files. Can fix broken cross-reference tables, corrupted object streams, missing headers, and encoding errors. + +Cannot recover physically deleted data. Success depends on extent of corruption. --- @@ -150,20 +61,7 @@ Attempt to repair corrupted or damaged PDF files. **Tool ID:** `scannerImageSplit` -Automatically detect and split individual scanned photos from multi-image PDF scans. - -#### What it does -- Detect individual images/photos on pages -- Automatically separate them into individual files -- Useful for batch-scanned photo collections -- Crop and extract each image separately -- Support for various scan layouts - -#### Perfect for -- Separating batch-scanned photos -- Extracting individual images from collection scans -- Processing multi-photo scanner output -- Organizing photo digitization projects +Automatically detect and split individual scanned photos from multi-image PDF scans. Useful for batch-scanned photo collections. --- @@ -171,27 +69,7 @@ Automatically detect and split individual scanned photos from multi-image PDF sc **Tool ID:** `overlayPdfs` -Merge multiple PDFs by layering them on top of each other. - -#### What it does -- Layer one PDF on top of another -- Position overlay precisely -- Control opacity/transparency -- Place content on foreground or background -- Apply to specific pages or all pages - -#### Perfect for -- Adding letterheads to documents -- Applying template backgrounds -- Watermarking with complex designs -- Creating layered composite documents -- Merging forms with filled data - -#### Overlay Options -- **Position:** Top, bottom, centered, custom coordinates -- **Mode:** Foreground or background -- **Opacity:** Full or partial transparency -- **Pages:** All pages, specific ranges, or alternating +Layer one PDF on top of another. Control position, opacity, and whether the overlay appears in the foreground or background. Apply to specific pages or all pages. --- @@ -199,26 +77,7 @@ Merge multiple PDFs by layering them on top of each other. **Tool ID:** `replaceColor` -Replace specific colors in a PDF or invert all colors. - -#### What it does -- Replace one color with another -- Invert all colors (create negative) -- Adjust color schemes -- Make PDFs printer-friendly -- Create dark mode versions - -#### Perfect for -- Creating negative images -- Changing color schemes for printing -- Making dark backgrounds light (and vice versa) -- Correcting color issues -- Accessibility improvements - -#### Options -- **Invert All:** Complete color negative -- **Replace Color:** Specify source and target colors -- **Threshold:** Control color matching sensitivity +Replace specific colors in a PDF or invert all colors. Options include full color inversion, targeted color replacement, and adjustable matching threshold. --- @@ -226,21 +85,7 @@ Replace specific colors in a PDF or invert all colors. **Tool ID:** `addImage` -Add or overlay images onto PDF pages. - -#### What it does -- Insert images into PDFs -- Position images precisely -- Resize and scale images -- Add images to specific pages -- Support for various image formats - -#### Perfect for -- Adding logos to documents -- Inserting photos into reports -- Creating visual composites -- Adding signatures or stamps as images -- Enhancing documents with graphics +Insert images into PDF pages with precise positioning and sizing. Supports common image formats. --- @@ -248,139 +93,23 @@ Add or overlay images onto PDF pages. **Tool ID:** `scannerEffect` -Apply realistic scanner-like effects to PDFs to make them appear scanned. - -#### What it does -- Add authentic scan appearance -- Slight rotation/skew effects -- Simulate scanner artifacts -- Adjust for realistic paper texture -- Make digital documents look scanned - -#### Perfect for -- Making digital documents appear scanned -- Adding authenticity to digital forms -- Creating realistic-looking scans from digital content +Apply realistic scanner-like effects to digital PDFs - slight rotation/skew and scan artifacts to make documents appear physically scanned. --- ## Developer Tools -These tools provide access to technical documentation and setup guides. - ### Show JavaScript **Tool ID:** `showJS` -Display any embedded JavaScript code within a PDF document. - -#### What it does -- Extract and display all JavaScript from PDF -- Security analysis of PDF scripts -- Identify potentially harmful code -- Review PDF automation scripts -- Debug PDF form behaviors - -#### Perfect for -- Security auditing of PDFs -- Identifying malicious scripts -- Understanding PDF form logic -- Debugging interactive PDFs -- Compliance review - ---- - -### API Documentation - -**Tool ID:** `devApi` - -Quick link to complete API documentation for integrating Stirling PDF into your applications. - -**Access:** [API Documentation](../API.md) - ---- - -### Folder Scanning Guide - -**Tool ID:** `devFolderScanning` - -Link to comprehensive guide for setting up automated folder scanning with pipelines. - -**Access:** [Folder Scanning Setup](../Configuration/FolderScanning.md) - ---- - -### SSO Configuration - -**Tool ID:** `devSsoGuide` - -Link to Single Sign-On (SSO) configuration guide for enterprise deployments. - -**Access:** [SSO Guide](../Configuration/Single%20Sign-On%20Configuration.md) - ---- - -### Air-gapped Setup - -**Tool ID:** `devAirgapped` - -Link to guide for deploying Stirling PDF in offline/air-gapped environments. - -**Access:** [Configuration](../Configuration/Configuration.md) - ---- - -## When to Use Advanced Tools - -Use advanced tools when you need to: -- ✅ Automate repetitive multi-step PDF operations -- ✅ Fix corrupted or damaged PDF files -- ✅ Perform complex color or image manipulations -- ✅ Organize large document collections automatically -- ✅ Integrate PDF operations into existing workflows -- ✅ Audit PDFs for security concerns -- ✅ Create sophisticated document processing pipelines - ---- - -## Automation Best Practices - -### For Automate/Pipeline: -1. **Start simple** - Test with one operation, then add more -2. **Use test files** - Verify pipelines work before production use -3. **Save configurations** - Reuse successful workflows -4. **Document workflows** - Add descriptions to saved pipelines -5. **Monitor folder scanning** - Check logs for errors - -### For Auto Rename: -1. **Test first** - Run on small batches to verify naming -2. **Use OCR first** - For scanned documents without text layer -3. **Review suggestions** - Check names before batch applying -4. **Backup originals** - Keep copies with original names - -### For Advanced Formatting: -1. **Preview changes** - Always preview before applying -2. **Test on copies** - Work with duplicates of important files -3. **Incremental adjustments** - Make small changes and iterate -4. **Document settings** - Note successful parameters for reuse - ---- - -## Related Documentation - -- **[Recommended Tools](./Recommended-Tools.md)** - Most common operations -- **[Complete Tool Reference](./Functionality.md)** - All 60+ tools -- **[Pipeline Configuration](./Features%20Pipeline.md)** - Automation workflows -- **[API Documentation](../API.md)** - Programmatic access -- **[Configuration](../Configuration/Configuration.md)** - System setup +Display any embedded JavaScript code within a PDF document. Useful for security auditing and understanding PDF form logic. --- -## Tips for Power Users +### Quick Links -1. **Combine tools strategically** - Use Automate to chain operations -2. **Leverage folder scanning** - Set up watch folders for automatic processing -3. **Use API for integration** - Integrate with your existing systems -4. **Save pipeline configs** - Reuse proven workflows -5. **Monitor and optimize** - Review performance and adjust settings -6. **Share configurations** - Pre-load pipelines for team use +- **[API Documentation](../API.md)** +- **[Folder Scanning Setup](../Configuration/FolderScanning.md)** +- **[SSO Configuration](../Configuration/Single%20Sign-On%20Configuration.md)** +- **[General Configuration](../Configuration/Configuration.md)** diff --git a/docs/Functionality/Compare.md b/docs/Functionality/Compare.md index b359f66d..448bea0e 100644 --- a/docs/Functionality/Compare.md +++ b/docs/Functionality/Compare.md @@ -9,415 +9,37 @@ description: Compare two PDF documents and highlight differences **Tool ID:** `compare` -Compare two PDF documents side-by-side and visually highlight the differences between them. Perfect for reviewing document revisions, finding changes in contracts, and quality assurance workflows. +Compare two PDF documents and visually highlight word-level differences. Runs entirely in your browser - no files are sent to the server. --- -## What is PDF Comparison? - -PDF comparison analyzes two versions of a document and highlights: -- **Added content** - New text or elements in the newer version -- **Removed content** - Text or elements deleted from the original -- **Modified content** - Changes to existing text or formatting -- **Visual differences** - Layout or structural changes - -This is essential for document review, version control, and change tracking. - ---- - -## How to Use Compare +## How to Use 1. **Upload Original PDF** - Select the original/older version 2. **Upload Modified PDF** - Select the new/revised version -3. **Configure Comparison** - Adjust comparison settings (optional) -4. **Compare** - Process the documents -5. **Review Differences** - View highlighted changes side-by-side -6. **Navigate Changes** - Jump between differences -7. **Export Results** - Download comparison report (optional) - ---- - -## Comparison Features - -### Side-by-Side View - -View both documents simultaneously: -- **Original on left** - The base document -- **Modified on right** - The revised document -- **Synchronized scrolling** - Both pages move together -- **Aligned pages** - Easy comparison of corresponding pages - -### Difference Highlighting - -Visual indicators for changes: -- **Green highlighting** - Added content -- **Red highlighting** - Removed content -- **Yellow highlighting** - Modified content -- **Color-coded markers** - Quick identification of change types - -### Navigation Tools - -Efficiently review changes: -- **Next/Previous buttons** - Jump between differences -- **Change counter** - See total number of changes -- **Page navigation** - Move through document pages -- **Zoom controls** - Examine details closely - ---- - -## Comparison Settings - -### Comparison Mode - -**Text Comparison:** -- Compare text content only -- Ignore formatting changes -- Focus on wording differences -- Fast and efficient - -**Visual Comparison:** -- Compare entire page appearance -- Detect layout changes -- Include images and graphics -- More comprehensive - -**Hybrid Mode:** -- Combine text and visual comparison -- Best of both approaches -- Recommended for most use cases - -### Sensitivity Settings - -**Strict Mode:** -- Highlight every small change -- Include whitespace differences -- Detect minor formatting -- Most detailed comparison - -**Normal Mode:** -- Ignore minor formatting -- Focus on content changes -- Skip insignificant whitespace -- Balanced approach (recommended) - -**Lenient Mode:** -- Only major differences -- Ignore styling changes -- Focus on substantial edits -- Quick overview - -### Ignore Options - -Customize what to ignore: -- **Whitespace** - Spaces, tabs, line breaks -- **Case sensitivity** - Uppercase vs lowercase -- **Formatting** - Font, size, color -- **Metadata** - Author, dates, properties +3. **Compare** - Process the documents +4. **Review Differences** - View highlighted changes --- -## Use Cases +## Features -### Contract Review - -**Before signing:** -1. Compare original contract with revised version -2. Verify all requested changes were made -3. Check for unexpected modifications -4. Document all differences - -**Best Practices:** -- Always compare final version before signing -- Save comparison report for records -- Review every highlighted change -- Consult legal counsel on significant changes - -### Document Versioning - -**Version control:** -1. Compare current version with previous -2. Track changes over time -3. Identify who changed what -4. Maintain change history - -**Workflow:** -- Version 1 → Version 2 comparison -- Document all revisions -- Create audit trail -- Archive comparison results - -### Quality Assurance - -**Proofreading workflow:** -1. Compare draft with edited version -2. Verify all edits were applied -3. Check for unintended changes -4. Ensure consistency - -**Use For:** -- Editorial review -- Translation verification -- Compliance checking -- Final approval process - -### Compliance & Legal - -**Regulatory requirements:** -1. Compare submitted documents -2. Verify no unauthorized changes -3. Create audit trail -4. Meet compliance standards - -**Legal Discovery:** -- Document tampering detection -- Change authentication -- Evidence preservation -- Forensic analysis - ---- - -## Comparison Report - -### Report Contents - -Generated comparison report includes: -- **Summary statistics** - Total changes, added, removed, modified -- **Change list** - Detailed list of all differences -- **Location references** - Page and position of each change -- **Timestamp** - When comparison was performed -- **Document metadata** - File names, versions, dates - -### Export Options - -**PDF Report:** -- Highlighted differences embedded -- Side-by-side or overlay view -- Annotations for each change -- Shareable document - -**JSON Export:** -- Machine-readable format -- Automation-friendly -- Complete difference data -- Integration with other tools - -**Text Summary:** -- Human-readable list -- Quick overview -- Copy/paste friendly -- Email-ready format - ---- - -## Best Practices - -### Before Comparing - -1. **Verify file names** - Ensure you have the correct versions -2. **Check file dates** - Confirm which is newer -3. **Review context** - Understand what changes to expect -4. **Choose settings** - Select appropriate comparison mode - -### During Comparison - -1. **Review systematically** - Check every highlighted change -2. **Take notes** - Document important differences -3. **Verify intent** - Ensure changes match expectations -4. **Check thoroughly** - Don't miss subtle changes - -### After Comparison - -1. **Save report** - Keep record of differences -2. **Document findings** - Note any concerns -3. **Take action** - Address unexpected changes -4. **Archive results** - Maintain audit trail - ---- - -## Common Comparison Scenarios - -### Scenario 1: Contract Negotiation - -**Context:** Client returned contract with changes - -**Process:** -1. Upload original contract -2. Upload client's version -3. Use "Text Comparison" mode -4. Review all red/green highlights -5. Verify each change is acceptable -6. Generate comparison report for records - -### Scenario 2: Translation Verification - -**Context:** Verify translated document matches original - -**Process:** -1. Upload original language version -2. Upload translation -3. Use "Visual Comparison" mode -4. Check layout consistency -5. Verify images and graphics match -6. Ensure no content was lost - -### Scenario 3: Revision Tracking - -**Context:** Multiple editors worked on document - -**Process:** -1. Compare Version 1 → Version 2 -2. Compare Version 2 → Version 3 -3. Track cumulative changes -4. Document all modifications -5. Create comprehensive change log - ---- - -## Tips & Tricks - -### Comparison Accuracy - -**For Best Results:** -- Use digital PDFs (not scanned) for text comparison -- Ensure both PDFs are same page size -- Use consistent PDF versions -- Avoid heavily compressed files - -**For Scanned Documents:** -- Run [OCR](./OCR.md) on both documents first -- Use visual comparison mode -- Expect some false positives -- Manually verify important changes - -### Handling Large Documents - -**Performance Tips:** -- Compare section by section if very large -- Use text mode for faster processing -- Close other applications -- Consider using desktop app for big files - -### False Positives - -**Common causes:** -- Different PDF generators -- Font embedding differences -- Compression variations -- Metadata changes - -**Solutions:** -- Use "Normal" sensitivity mode -- Ignore formatting differences -- Focus on content changes -- Manually verify ambiguous changes - ---- - -## Technical Details - -### Comparison Algorithm - -Stirling PDF uses advanced comparison algorithms: -- **Text extraction** - Extract text from both PDFs -- **Diff algorithm** - Compute differences -- **Visual rendering** - Highlight changes -- **Alignment** - Match corresponding pages - -### Supported PDF Types - -**Works Best With:** -- ✅ Digital PDFs (not scanned) -- ✅ Text-based content -- ✅ Standard fonts -- ✅ Similar page layouts - -**Challenging Cases:** -- ⚠️ Scanned documents (use OCR first) -- ⚠️ Complex layouts -- ⚠️ Heavy graphics -- ⚠️ Different page sizes - -### Performance - -**Processing Time:** -- Text comparison: Fast (seconds) -- Visual comparison: Moderate (1-2 min) -- Large documents: May take longer - -**File Size Limits:** -- Browser: ~100-500 pages -- Desktop app: No practical limit +- **Side-by-side or stacked layout** - Toggle between horizontal and vertical views +- **Word-level diff** - Removed words highlighted in red, added words highlighted in green +- **Change navigation** - Dropdown selectors to jump between deletions and additions +- **Synchronized scrolling** - Optional linked scrolling between the two panes +- **Zoom and pan** - Scroll-wheel zoom, pinch-to-zoom, and drag to pan --- ## Limitations -### What Comparison Can't Do - -**Not Detected:** -- Semantic changes (same words, different meaning) -- Subtle formatting that doesn't render differently -- Changes in embedded media -- Metadata-only changes (unless specifically enabled) - -**False Positives:** -- Different PDF generators may show differences -- Font rendering variations -- Compression artifacts -- Trivial whitespace changes - -### Workarounds - -**For Better Comparison:** -- Use same PDF generator when possible -- Standardize fonts across versions -- Use "Normal" sensitivity to reduce noise -- Manually verify critical sections - ---- - -## API Usage - -Compare PDFs programmatically via API: - -```bash -curl -X POST http://stirling-pdf:8080/api/v1/compare \ - -F "file1=@original.pdf" \ - -F "file2=@modified.pdf" \ - -F "mode=text" \ - -F "sensitivity=normal" \ - -o comparison-report.pdf -``` - -**Parameters:** -- `file1` - Original/older document -- `file2` - Modified/newer document -- `mode` - `text`, `visual`, or `hybrid` -- `sensitivity` - `strict`, `normal`, or `lenient` -- `outputFormat` - `pdf`, `json`, or `text` - -See [API Documentation](../API.md) for complete endpoint reference. +- Works best with digital PDFs (not scanned). For scanned documents, run [OCR](./OCR.md) first +- Compares extracted text only - layout-only or image-only changes are not detected +- Very large or highly dissimilar documents may be stopped early with a warning --- ## Related Tools - **[OCR](./OCR.md)** - Make scanned PDFs searchable before comparing -- **[Multi-Tool](./Multi-Tool.md)** - Compare as part of a workflow -- **[Redact](./Page-Operations/redact.md)** - Remove sensitive differences before sharing comparison -- **[Merge](./Page-Operations/Page-Operations.md)** - Combine comparison results with originals - ---- - -## Summary - -Stirling PDF's Compare tool provides: - -✅ **Side-by-side comparison** - View both documents simultaneously -✅ **Visual highlighting** - Color-coded difference markers -✅ **Multiple modes** - Text, visual, or hybrid comparison -✅ **Customizable sensitivity** - Control detail level -✅ **Comparison reports** - Export results in multiple formats -✅ **Navigation tools** - Jump between changes efficiently - -Perfect for contract review, version control, quality assurance, and compliance workflows! diff --git a/docs/Functionality/Compress.md b/docs/Functionality/Compress.md index c9440e6e..cf7a1a19 100644 --- a/docs/Functionality/Compress.md +++ b/docs/Functionality/Compress.md @@ -9,338 +9,65 @@ description: Reduce PDF file size while maintaining quality **Tool ID:** `compress-pdf` -Reduce PDF file size while maintaining acceptable quality for your needs. Stirling PDF's compression tool optimizes images, removes unnecessary data, and applies various compression techniques to significantly reduce file sizes. - ---- - -## What is PDF Compression? - -PDF compression reduces file size by: -- Compressing embedded images -- Removing duplicate resources -- Optimizing fonts and content streams -- Removing unused or redundant data -- Downsampling high-resolution images +Reduce PDF file size by compressing images, optimizing structure, and removing unnecessary data. **Important:** Compression is permanent. Always keep a backup of the original if you might need maximum quality later. --- -## How to Use Compress +## How to Use -1. **Upload Your PDF** - Select one or more PDFs to compress +1. **Upload Your PDF** - Select one or more PDFs 2. **Choose Compression Level** - Select quality vs. size balance -3. **Configure Options** - Adjust advanced settings (optional) +3. **Configure Options** - Enable grayscale, line art, etc. (optional) 4. **Compress** - Process the files 5. **Download** - Get your compressed PDFs --- -## Compression Levels - -### Low Compression -- **Size Reduction:** ~10-30% -- **Quality:** Excellent - minimal quality loss -- **Best For:** - - Documents with important images - - Professional presentations - - Photos that need high quality - - Documents for printing - -**Use When:** You need smaller files but can't compromise on quality. - -### Medium Compression (Recommended) -- **Size Reduction:** ~30-60% -- **Quality:** Good - balanced quality/size tradeoff -- **Best For:** - - General documents - - Email attachments - - Web publishing - - Most use cases - -**Use When:** You want good file size reduction with acceptable quality. - -### High Compression -- **Size Reduction:** ~60-90% -- **Quality:** Fair - noticeable quality reduction -- **Best For:** - - Text-heavy documents - - Documents with simple graphics - - Archival storage where quality is secondary - - Very large documents that must be smaller - -**Use When:** File size is critical and quality is less important. - -### Custom Compression -- **Manual Control:** Set exact compression parameters -- **Advanced Users:** Fine-tune image DPI, quality, color depth -- **Testing:** Experiment to find optimal settings - ---- - -## Compression Options - -### Image Quality - -**Image DPI (Resolution):** -- **300 DPI** - High quality, suitable for printing -- **150 DPI** - Standard quality, good for screen viewing -- **72 DPI** - Low quality, very small files - -**Image Quality Percentage:** -- **90-100%** - Minimal compression, excellent quality -- **70-90%** - Balanced compression (recommended) -- **50-70%** - Aggressive compression, visible artifacts - -### Color Depth - -**Options:** -- **Full Color (24-bit)** - All colors preserved -- **Grayscale (8-bit)** - Convert to black/white shades -- **Monochrome (1-bit)** - Pure black and white only - -**Tip:** Convert color documents to grayscale if color isn't needed - can reduce size by 50%+. - -### Advanced Options - -**Optimize Images:** -- Compress and optimize all embedded images -- Downsample high-resolution images -- Remove image metadata - -**Remove Duplicate Resources:** -- Detect and remove duplicate images/fonts -- Significant savings for documents with repeated elements - -**Compress Content Streams:** -- Apply advanced compression to PDF content -- Optimize internal PDF structure - -**Remove Unused Objects:** -- Clean up leftover objects from editing -- Remove orphaned resources - ---- - -## What Gets Compressed? - -### Images -- JPEG images re-compressed at lower quality -- PNG images optimized and potentially converted -- High-resolution images downsampled -- Duplicate images removed - -### Fonts -- Subset fonts (include only used characters) -- Remove unused font data -- Optimize font embedding +## Options -### Content -- Compress content streams with ZLIB/DEFLATE -- Optimize PDF structure -- Remove redundant data - -### Metadata -- Optionally remove or reduce metadata -- Remove thumbnail previews -- Strip editing history +| Option | Description | +|--------|-------------| +| **Optimize Level** (1-9) | Controls compression aggressiveness. Higher = smaller file, lower quality. Levels 1-3 are light, 4-5 are moderate, 6+ trigger additional compression passes | +| **Expected Output Size** | Set a target file size (e.g. `25MB`) and the tool will automatically adjust the optimize level to hit it | +| **Grayscale** | Convert all images to grayscale. Can significantly reduce size for color documents where color isn't needed | +| **Linearize** | Optimize PDF for fast web viewing - reorders the file so the first page loads before the entire file is downloaded | +| **Normalize** | Normalize internal PDF structure for better compatibility | +| **Line Art** | Convert images to high-contrast line art. Useful for documents with diagrams, sketches, or black-and-white illustrations | +| **Line Art Threshold** (0-100) | Controls sensitivity of line art conversion. Default: 55. Only used when Line Art is enabled | +| **Line Art Edge Level** (1-3) | Edge detection strength for line art. 1 = light, 3 = strong. Only used when Line Art is enabled | --- -## Tips & Best Practices - -### Before Compressing - -1. **Keep a backup** - Compression is permanent -2. **Test on a copy** - Try different settings first -3. **Check file size** - Already compressed? May not reduce much -4. **Identify content type** - Text vs. images requires different approaches - -### Choosing Compression Level - -**For Text-Heavy Documents:** -- ✅ High compression works well -- ✅ Text quality remains excellent -- ✅ 70-90% size reduction common - -**For Image-Heavy Documents:** -- ⚠️ Start with medium compression -- ⚠️ Test before applying to batch -- ⚠️ 30-60% size reduction typical +## What Happens at Each Level -**For Mixed Content:** -- ✅ Medium compression (recommended) -- ✅ Test on sample pages -- ✅ 40-70% size reduction expected - -### After Compressing - -1. **Verify quality** - Open and review compressed PDF -2. **Check images** - Zoom in on important images -3. **Test printing** - If document will be printed -4. **Compare file sizes** - Ensure compression worked - ---- - -## Common Issues - -### "File not compressing much" - -**Possible Causes:** -- PDF already compressed -- Mostly text with few images -- Images already optimized - -**Solutions:** -- Try higher compression level -- Check if file is already compressed -- Some PDFs have minimal compression potential - -### "Quality too poor after compression" - -**Possible Causes:** -- Compression level too high -- Source images low quality -- DPI set too low - -**Solutions:** -- Reduce compression level -- Increase image DPI setting -- Use "Medium" or "Low" compression -- Keep original for high-quality needs - -### "Compression failed" - -**Possible Causes:** -- Corrupted PDF -- Encrypted/password-protected PDF -- Unusual PDF structure - -**Solutions:** -- Try repairing PDF first -- Remove password protection -- Try different compression settings - ---- - -## Batch Compression - -Compress multiple PDFs at once with consistent settings: - -1. **Upload Multiple Files** - Select multiple PDFs -2. **Choose Settings** - Apply same settings to all -3. **Process Batch** - Compress all files -4. **Download ZIP** - Get all compressed PDFs in one archive - -**Tip:** Test settings on one file first, then apply to batch. - ---- - -## Compression vs. File Size - -### Expected Results - -| Original Size | Compression Level | Expected Result | Typical Output | -|--------------|-------------------|-----------------|----------------| -| 50 MB | Low | ~10-30% | 35-45 MB | -| 50 MB | Medium | ~30-60% | 20-35 MB | -| 50 MB | High | ~60-90% | 5-20 MB | - -**Note:** Actual results vary based on content type (text vs. images) and whether file is already compressed. - -### Document Type Comparison - -**Scanned Documents (Image-heavy):** -- Excellent compression potential -- 60-90% reduction common with high compression -- Most benefit from compression - -**Digital PDFs (Text-heavy):** -- Moderate compression potential -- 20-40% reduction typical -- Already relatively small - -**Mixed Content:** -- Good compression potential -- 40-70% reduction expected -- Varies by image/text ratio - ---- - -## Technical Details - -### Compression Methods - -Stirling PDF uses multiple compression techniques: - -**Image Compression:** -- JPEG compression for photos -- FLATE compression for graphics -- Downsampling for high-resolution images - -**Content Stream Compression:** -- ZLIB/DEFLATE algorithms -- Object stream compression -- Cross-reference stream compression - -**Structure Optimization:** -- Remove unused objects -- Deduplicate resources -- Optimize PDF structure - -### Processing Engine - -Uses **Apache PDFBox** and **ImageMagick** for compression: -- Industry-standard tools -- Proven reliability -- Wide format support - ---- - -## Use with Other Tools - -### Common Workflows - -**Scan → OCR → Compress** -1. Scan documents to PDF -2. [OCR](./OCR.md) to make searchable -3. Compress to reduce file size - -**Merge → Compress** -1. [Merge](./Page-Operations/Page-Operations.md) multiple PDFs -2. Compress combined document -3. Share smaller file - -**Convert → Compress** -1. [Convert](./Convert/Convert.md) images to PDF -2. Compress to optimize size -3. Email or upload - -**Edit → Compress → Archive** -1. Edit and modify PDFs -2. Compress for storage -3. Archive with smaller footprint +- **Levels 1-3** - Basic optimization, preserves quality +- **Levels 4-5** - Image recompression enabled, moderate quality reduction +- **Levels 6+** - Aggressive compression with additional processing passes +- **Levels 8+** - Uses Zopfli compression on supported systems for maximum reduction --- ## API Usage -Compress PDFs programmatically via API: - ```bash -curl -X POST http://stirling-pdf:8080/api/v1/compress/pdf \ +curl -X POST http://stirling-pdf:8080/api/v1/misc/compress-pdf \ -F "fileInput=@document.pdf" \ - -F "optimizeLevel=2" \ - -F "imageQuality=70" \ - -F "imageDpi=150" \ + -F "optimizeLevel=5" \ + -F "grayscale=false" \ + -F "linearize=false" \ + -F "lineArt=false" \ -o compressed.pdf ``` -**Parameters:** -- `optimizeLevel` - 0 (low), 1 (medium), 2 (high) -- `imageQuality` - 1-100 (percentage) -- `imageDpi` - Target DPI for images -- `fastWebView` - Optimize for web streaming +With target size: +```bash +curl -X POST http://stirling-pdf:8080/api/v1/misc/compress-pdf \ + -F "fileInput=@document.pdf" \ + -F "expectedOutputSize=10MB" \ + -o compressed.pdf +``` See [API Documentation](../API.md) for complete endpoint reference. @@ -350,20 +77,4 @@ See [API Documentation](../API.md) for complete endpoint reference. - **[OCR](./OCR.md)** - Make searchable before compressing - **[Convert](./Convert/Convert.md)** - Convert formats before compressing -- **[Multi-Tool](./Multi-Tool.md)** - Chain compression with other operations - **[Merge](./Page-Operations/Page-Operations.md)** - Combine then compress - ---- - -## Summary - -Stirling PDF's Compress tool provides: - -✅ **Significant size reduction** - 10-90% smaller files -✅ **Quality control** - Choose your size/quality balance -✅ **Batch processing** - Compress multiple files at once -✅ **Smart optimization** - Multiple compression techniques -✅ **Flexible options** - Fine-tune for your needs -✅ **API access** - Automate compression workflows - -Perfect for reducing email attachment sizes, optimizing storage, and speeding up file transfers! diff --git a/docs/Functionality/Content-Editing/Content-Editing.md b/docs/Functionality/Content-Editing/Content-Editing.md index 1a77761e..76473953 100644 --- a/docs/Functionality/Content-Editing/Content-Editing.md +++ b/docs/Functionality/Content-Editing/Content-Editing.md @@ -22,21 +22,21 @@ Tools for adding, extracting, and modifying content within PDF documents. ## Stamps & Annotations -- `add-stamp`: Add user-defined text or image stamps to PDF pages with customizable position, size, rotation, and opacity. Can be applied to specific pages or all pages. Perfect for approval stamps, confidential markings, or custom branding. +- `add-stamp`: Add user-defined text or image stamps to PDF pages with customizable position, size, rotation, and opacity. Can be applied to specific pages or all pages. -- `remove-annotations`: Remove all annotations, comments, and markup from a PDF document while preserving the original content. Useful for creating clean versions of reviewed documents. +- `remove-annotations`: Remove all annotations, comments, and markup from a PDF document while preserving the original content. --- ## Visual Editing -- `replace-color`: Replace specific colors in a PDF or invert all colors. Useful for creating negative images, changing color schemes, or making documents printer-friendly. +- `replace-color`: Replace specific colors in a PDF or invert all colors. --- ## Metadata & Information -- `change-metadata`: Change the metadata of a PDF, including author name, title, subject, keywords, creation date, and more. Essential for document organization and compliance. +- `change-metadata`: Change the metadata of a PDF, including author name, title, subject, keywords, creation date, and more. - `get-info-on-pdf`: Extract and display comprehensive information about a PDF including: - PDF version and file size @@ -44,63 +44,7 @@ Tools for adding, extracting, and modifying content within PDF documents. - Fonts used - Security settings and permissions - Complete metadata - - Export all information in JSON format for automation - ---- - -## Tips & Use Cases - -### Working with Images - -**Adding Images:** -- Use for logos, signatures, or decorative elements -- Position precisely with drag-and-drop -- Adjust transparency to blend with document - -**Extracting Images:** -- Pull images from PDFs for reuse -- Extract scanned photos -- Batch extract from multiple documents - -### Stamps & Branding - -**Common Stamp Uses:** -- "APPROVED" / "CONFIDENTIAL" markers -- Company logos on every page -- Date/time stamps -- Custom approval workflows - -**Pre-configured Stamps:** -- Configure common stamps for quick access -- Team-wide stamp templates -- Consistent branding across documents - -### Color Management - -**Replace Color Uses:** -- Convert dark backgrounds to white (printer-friendly) -- Create negative images -- Change brand colors -- Fix color issues in scanned documents - -**Invert Colors:** -- Create dark mode versions -- Photography negative effects -- Improve readability - -### Metadata Management - -**Why Metadata Matters:** -- Document organization and searchability -- Compliance requirements (author, date) -- Version tracking -- Legal discovery - -**Metadata Best Practices:** -- Set author/title for all documents -- Use keywords for searchability -- Include creation date -- Remove sensitive metadata before sharing + - Export all information in JSON format --- @@ -109,4 +53,3 @@ Tools for adding, extracting, and modifying content within PDF documents. - **[OCR](../OCR.md)** - Make scanned images searchable before extracting text - **[Compress](../Compress.md)** - Reduce file size after adding images - **[Security](../Security/Security.md)** - Add watermarks or sanitize metadata -- **[Multi-Tool](../Multi-Tool.md)** - Chain content editing with other operations diff --git a/docs/Functionality/Convert/Convert.md b/docs/Functionality/Convert/Convert.md index 8efb635e..cc345b8f 100644 --- a/docs/Functionality/Convert/Convert.md +++ b/docs/Functionality/Convert/Convert.md @@ -2,20 +2,21 @@ sidebar_position: 2 description: Convert files to and from PDF format --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Convert -Stirling PDF's Convert tool provides powerful file format conversion with support for 50+ file types. Convert documents, images, web pages, and more to PDF, or export PDFs to other formats. +Convert between PDF and 50+ file formats including documents, images, web pages, and more. --- -## How to Use Convert +## How to Use -1. **Select Source Format** - Choose what you're converting from (e.g., Word, Image, PDF) -2. **Select Target Format** - Choose what you're converting to (e.g., PDF, JPG, DOCX) -3. **Upload Files** - Add one or multiple files depending on the conversion -4. **Configure Options** - Adjust settings like image quality, color mode, layout -5. **Convert** - Process and download your converted files +1. **Select conversion type** - Choose what you're converting from and to +2. **Upload files** - Add one or multiple files +3. **Configure options** - Adjust quality, DPI, layout (optional) +4. **Convert** - Process and download --- @@ -23,267 +24,72 @@ Stirling PDF's Convert tool provides powerful file format conversion with suppor ### Convert TO PDF -#### Office Documents -- **Word** - DOCX, DOC, ODT → PDF -- **Excel** - XLSX, XLS, ODS → PDF -- **PowerPoint** - PPTX, PPT, ODP → PDF -- **Text** - TXT, RTF → PDF - -#### Images -- **Formats** - JPG, JPEG, PNG, GIF, BMP, TIFF, WEBP, SVG → PDF -- **Multiple Images** - Combine multiple images into one PDF -- **Options:** - - Color mode (color, grayscale, black & white) - - Fit to page or maintain aspect ratio - - Single PDF or separate files - -#### Web Content -- **HTML to PDF** - Convert HTML files (with CSS and images via ZIP) -- **URL to PDF** - Render and save web pages as PDF -- **Markdown to PDF** - Convert Markdown (.md) files to formatted PDF - -#### Email -- **EML to PDF** - Convert email files (.eml format) into PDF -- Preserves email content, formatting, and metadata - -#### Comic Book Archives -- **CBZ to PDF** - Convert Comic Book Zip files to PDF -- **CBR to PDF** - Convert Comic Book RAR files to PDF - ---- +| Category | Formats | +|----------|---------| +| **Office** | DOCX, DOC, ODT, XLSX, XLS, ODS, PPTX, PPT, ODP, TXT, RTF | +| **Images** | JPG, JPEG, PNG, GIF, BMP, TIFF, WEBP, SVG | +| **Web** | HTML (with CSS/images via ZIP), URL, Markdown | +| **Email** | EML | +| **Comics** | CBZ, CBR | ### Convert FROM PDF -#### Office Formats -- **PDF to Word** - PDF → DOCX, ODT - - Editable documents with preserved layout - - Best for text-heavy PDFs - - Works better with digital PDFs than scanned ones - -- **PDF to PowerPoint** - PDF → PPTX, ODP - - Each page becomes a slide - - Useful for presentations - -- **PDF to Text** - PDF → TXT, RTF, MD (Markdown) - - Extract plain text - - Remove formatting - - Easy to edit and search - -#### Images -- **PDF to Image** - PDF → PNG, JPG, GIF, TIFF, BMP, WEBP -- **Options:** - - Image format and quality - - DPI (resolution) - - Color mode (color, grayscale, black & white) - - Single image or one per page - -#### Data Formats -- **PDF to CSV** - Extract tables from PDF to CSV - - ⚠️ Works best with digital PDFs (not scanned) - - Attempts to detect tables automatically - - Work in progress feature due to complexity - -- **PDF to HTML** - Convert PDF to web format - - Preserves structure and formatting - - Can be edited with HTML editors - -- **PDF to XML** - Convert PDF to XML structure - - For data processing and analysis - -#### Archival Format -- **PDF to PDF/A** - Convert to long-term archival format - - PDF/A is ISO standardized - - Ensures long-term readability - - Required for compliance in many industries - -#### Comic Book Archives -- **PDF to CBZ** - Convert PDF to Comic Book Zip -- **PDF to CBR** - Convert PDF to Comic Book RAR +| Category | Formats | +|----------|---------| +| **Office** | DOCX, ODT, PPTX, ODP, TXT, RTF, Markdown | +| **Images** | PNG, JPG, GIF, TIFF, BMP, WEBP | +| **Data** | CSV, HTML, XML | +| **Archival** | PDF/A | +| **Comics** | CBZ, CBR | --- ## Conversion Options -### Image Quality Settings - -**When converting to images:** -- **DPI (Resolution)** - - 72 DPI - Screen viewing, small file size - - 150 DPI - Standard quality, balanced - - 300 DPI - High quality, printing, large file size - - Custom - Specify exact DPI - -- **Color Mode** - - **Color** - Full color, best quality - - **Grayscale** - Black and white shades, smaller file - - **Black & White** - 1-bit, smallest file, sharp text - -### Layout Options - -**When converting images to PDF:** -- **Fit to Page** - Resize image to fit PDF page -- **Maintain Aspect Ratio** - Keep original proportions -- **Fill Page** - Stretch to fill entire page - -**Output Mode:** -- **Single PDF** - All files into one PDF -- **Separate PDFs** - One PDF per input file - ---- - -## Batch Conversion - -Convert multiple files at once: - -1. Select conversion type (e.g., Images to PDF) -2. Upload multiple files -3. Choose "Single PDF" or "Separate PDFs" -4. Convert all at once -5. Download as single file or ZIP - -**Supported for:** -- Multiple images to PDF -- Multiple Office documents to PDF -- PDF to multiple images (one per page) - ---- - -## Tips & Best Practices - -### For Best Results - -**Office to PDF:** -- Use original source files (DOCX, not scanned) -- Check fonts are embedded -- Verify hyperlinks work -- Test on sample first for large documents +### Image Settings (when converting to/from images) +- **DPI:** 72 (screen), 150 (standard), 300 (print) +- **Color Mode:** Color, Grayscale, Black & White +- **Layout:** Fit to page, maintain aspect ratio, fill page +- **Output:** Single PDF or separate files -**PDF to Office:** +### PDF to Word / Office - Works best with digital PDFs (not scanned images) -- For scanned PDFs, use OCR first -- Complex layouts may need manual adjustment -- Check formatting after conversion +- For scanned PDFs, run [OCR](../OCR.md) first +- Complex layouts may need manual adjustment after conversion -**Image Conversions:** -- Higher DPI = better quality but larger files -- Use PNG for screenshots (lossless) -- Use JPG for photos (smaller) -- Grayscale reduces file size significantly - -**Web to PDF:** -- URLs must be publicly accessible -- For HTML files, include CSS/images in ZIP -- Test with simple pages first -- May timeout on very heavy pages - -### Common Issues - -**"Conversion failed"** -- Check file isn't corrupted -- Try smaller file first -- Ensure format is supported -- Check file isn't password-protected - -**"Poor quality output"** -- Increase DPI for image exports -- Use color mode instead of black/white -- Check source file quality -- Try different output format - -**"Tables not detected" (PDF to CSV)** -- Feature works best with simple tables -- Only works with digital PDFs, not scanned -- Consider extracting as text first -- Manual cleanup may be needed +### PDF to CSV +- Works best with simple, well-structured tables in digital PDFs +- Not reliable for scanned documents --- -## Technical Details - -### Processing Engine - -Stirling PDF uses industry-standard tools for conversions: - -- **Office Conversions** - LibreOffice (document fidelity) -- **Image Processing** - ImageMagick, OpenCV -- **PDF Operations** - Apache PDFBox -- **OCR** - Tesseract (when needed) - -### Supported Formats - -**Input Formats (Convert TO PDF):** -``` -Documents: DOCX, DOC, ODT, XLSX, XLS, ODS, PPTX, PPT, ODP, TXT, RTF -Images: JPG, JPEG, PNG, GIF, BMP, TIFF, WEBP, SVG -Web: HTML, ZIP (HTML bundle), Markdown (MD), URL -Email: EML -Archives: CBZ, CBR -``` - -**Output Formats (Convert FROM PDF):** -``` -Documents: DOCX, ODT, PPTX, ODP, TXT, RTF, MD -Images: PNG, JPG, GIF, TIFF, BMP, WEBP -Data: CSV, HTML, XML -Archive: PDF/A, CBZ, CBR -``` - -### File Size Limits +## API Usage -- **Web Version** - Depends on browser storage (typically ~1-10GB) -- **Desktop App** - No practical limit (disk space) -- **Server Deployment** - Configurable in settings + + + ```bash + curl -X POST http://stirling-pdf:8080/api/v1/convert/img/pdf \ + -F "fileInput=@image.jpg" \ + -F "colorType=color" \ + -F "fitOption=maintainAspectRatio" \ + -o output.pdf + ``` + + + ```bash + curl -X POST http://stirling-pdf:8080/api/v1/convert/pdf/word \ + -F "fileInput=@document.pdf" \ + -o output.docx + ``` + + -**For large files:** -- Use Desktop app for unlimited storage -- Split large PDFs before converting -- Process in batches -- Consider compression after conversion +See [API Documentation](../../API.md) for complete endpoint reference. --- ## Related Tools - **[Compress](../Compress.md)** - Reduce file size after conversion -- **[OCR](../OCR.md)** - Make scanned PDFs searchable before converting to text +- **[OCR](../OCR.md)** - Make scanned PDFs searchable before converting - **[Merge](../Page-Operations/Page-Operations.md)** - Combine multiple converted PDFs -- **[Multi-Tool](../Multi-Tool.md)** - Chain conversions with other operations - ---- - -## API Usage - -Convert files programmatically via API: - -**Example: Image to PDF** -```bash -curl -X POST http://stirling-pdf:8080/api/v1/convert/img/pdf \ - -F "fileInput=@image.jpg" \ - -F "colorType=color" \ - -F "fitOption=maintainAspectRatio" \ - -o output.pdf -``` - -**Example: PDF to Word** -```bash -curl -X POST http://stirling-pdf:8080/api/v1/convert/pdf/word \ - -F "fileInput=@document.pdf" \ - -o output.docx -``` - -See [API Documentation](../../API.md) for complete endpoint reference. - ---- - -## Summary - -Stirling PDF's Convert tool provides: - -✅ **50+ file format conversions** -✅ **Batch processing** - Convert multiple files at once -✅ **Quality control** - Adjust DPI, color mode, layout -✅ **Professional results** - Industry-standard conversion engines -✅ **No size limits** - Desktop app handles any file size -✅ **API access** - Automate conversions - -Perfect for document management, archiving, sharing, and workflow automation! diff --git a/docs/Functionality/Functionality.md b/docs/Functionality/Functionality.md index 71bfb0c4..0d2ad9eb 100644 --- a/docs/Functionality/Functionality.md +++ b/docs/Functionality/Functionality.md @@ -3,20 +3,18 @@ sidebar_position: 0 slug: /functionality id: Functionality title: PDF Tools -description: Explore 60+ PDF tools for all your document needs +description: All PDF tools organized by category --- # PDF Tools -Stirling PDF provides **60+ powerful PDF tools** organized by category. Find the tool you need below. +All tools organized by category. --- -## 🌟 Most Popular +## Most Popular -The tools you'll use most often: - -- **[Multi-Tool](./Multi-Tool.md)** - Upload once, chain unlimited operations +- **[Multi-Tool](./Multi-Tool.md)** - Upload once, chain operations - **[Read & Annotate](./Read-and-Annotate.md)** - PDF viewer with annotations - **Merge** - Combine multiple PDFs - **[Convert](./Convert/Convert.md)** - 50+ format conversions @@ -25,14 +23,9 @@ The tools you'll use most often: - **[Compare](./Compare.md)** - See differences between PDFs - **Redact** - Remove sensitive content -**[View Recommended Tools Guide →](./Recommended-Tools.md)** - --- -## 📚 Tools by Category - -### 🔐 [Security](./Security/Security.md) -Password protection, signatures, permissions, watermarks +## [Security](./Security/Security.md) - Add/Remove Password - Change Permissions @@ -45,8 +38,7 @@ Password protection, signatures, permissions, watermarks --- -### 📑 [Page Operations](./Page-Operations/Page-Operations.md) -Split, merge, rotate, extract, reorganize pages +## [Page Operations](./Page-Operations/Page-Operations.md) - Split PDF - Merge PDFs @@ -60,8 +52,7 @@ Split, merge, rotate, extract, reorganize pages --- -### 🔄 [Convert](./Convert/Convert.md) -Convert to/from PDF - 50+ file formats supported +## [Convert](./Convert/Convert.md) **To PDF:** Word, Excel, PowerPoint, Images, HTML, Markdown, Email, and more @@ -69,8 +60,7 @@ Convert to/from PDF - 50+ file formats supported --- -### 🎨 [Content & Editing](./Content-Editing/Content-Editing.md) -Add, extract, and modify PDF content +## [Content & Editing](./Content-Editing/Content-Editing.md) - Add/Extract Images - Add Stamp @@ -81,27 +71,19 @@ Add, extract, and modify PDF content --- -## ⚡ Advanced Features - -### 🎨 Super Tools -- **[Multi-Tool](./Multi-Tool.md)** - Workbench for chaining operations -- **[Read & Annotate](./Read-and-Annotate.md)** - PDF viewer with annotations -- **[OCR](./OCR.md)** - Make scanned PDFs searchable -- **[Compress](./Compress.md)** - Reduce file size -- **[Automate (Pipeline)](../Configuration/Pipeline.md)** - Workflow automation +## [Advanced Tools](./Advanced-Tools.md) -### 🔧 [Advanced Tools](./Advanced-Tools.md) -- Add Background/Stamp -- Booklet Imposition - Overlay PDFs +- Booklet Imposition - Multi-Page Layout - Scale Pages +- Auto Rename - Show JavaScript -- PDF Info (JSON) +- Scanner Effect --- -## 🔍 Quick Tool Finder +## Quick Tool Finder **I want to...** - Reduce file size → **[Compress](./Compress.md)** @@ -112,6 +94,4 @@ Add, extract, and modify PDF content - Add signature → **[Sign](./Security/Sign.md)** or **[Certificate Sign](./Security/Certificate-Signing.md)** - Remove content → **Redact** or **Sanitize** - Edit pages → **Reorganize Pages** or **[Multi-Tool](./Multi-Tool.md)** -- Chain operations → **[Multi-Tool](./Multi-Tool.md)** - Automate workflow → **[Automate](../Configuration/Pipeline.md)** - diff --git a/docs/Functionality/Mobile-Scanner.md b/docs/Functionality/Mobile-Scanner.md index ce0ba2e2..bf2b472e 100644 --- a/docs/Functionality/Mobile-Scanner.md +++ b/docs/Functionality/Mobile-Scanner.md @@ -6,7 +6,7 @@ description: Scan documents from your mobile phone and upload them directly to y # Mobile Scanner (Phone Upload) -The Mobile Scanner lets you scan documents using your phone camera and upload them directly to your Stirling PDF instance. Generate a QR code on your desktop, scan it with your phone, and your photos are transferred automatically — no cables, no cloud services, no manual file handling. +The Mobile Scanner lets you scan documents using your phone camera and upload them directly to your Stirling PDF instance. Generate a QR code on your desktop, scan it with your phone, and your photos are transferred automatically - no cables, no cloud services, no manual file handling. Depending on your [server settings](/Configuration/Mobile-Scanner), uploaded images can be automatically converted to PDF with configurable page format, resolution, and scaling options. diff --git a/docs/Functionality/Multi-Tool.md b/docs/Functionality/Multi-Tool.md index 1e7036bf..f02ee9a5 100644 --- a/docs/Functionality/Multi-Tool.md +++ b/docs/Functionality/Multi-Tool.md @@ -2,438 +2,57 @@ sidebar_position: 7 id: Multi-Tool title: Multi-Tool Workbench -description: Chain multiple PDF operations together without re-uploading files +description: Visual page editor for PDF manipulation --- # Multi-Tool Workbench **Tool ID:** `multiTool` -Multi-Tool is Stirling PDF's page editor workspace. Upload your PDFs and manipulate pages visually - rotate, reorder, delete, and split pages with an intuitive interface. +Multi-Tool is Stirling PDF's visual page editor. Upload PDFs and manipulate pages directly - rotate, reorder, delete, split, and insert pages or files. :::tip V2.0 Feature -Multi-Tool takes advantage of browser file storage, allowing you to upload files once and work with them across multiple page operations without re-uploading. +Multi-Tool uses browser file storage so you can upload files once and work with them without re-uploading. ::: --- -## What is Multi-Tool? +## Features -Multi-Tool is a page manipulation workspace where you can: -- Upload PDFs and see thumbnail previews of every page -- Rotate pages individually or in batches -- Reorder pages by dragging them into position -- Delete unwanted pages -- Split PDFs by marking page breaks -- Undo/redo all changes before exporting +- **Thumbnail grid** - See every page at a glance with zoomable previews +- **Rotate** pages left/right, individually or in bulk +- **Reorder** pages by dragging and dropping +- **Delete** unwanted pages +- **Split** PDFs by toggling split positions between pages +- **Insert page breaks** - add blank pages at any position +- **Insert files** - add entire PDFs into the document at any point +- **Select pages** individually, select all, or by page number range +- **Export selected** pages or save the full document +- **Undo/redo** all changes --- -## Key Features +## How to Use -### 📁 Persistent File Storage -Files stay in your browser's local storage throughout your session: -- Upload once, use many times -- No re-uploading between operations -- Files persist even when switching tools -- Clear storage when done for privacy - -### 📄 Page Manipulation -Powerful page-level editing: -- Rotate pages individually or in batches -- Drag-and-drop page reordering -- Delete unwanted pages -- Split PDFs at marked positions - -### 👁️ Visual File Management -See what you're working with: -- Thumbnail previews of all PDFs -- File names and sizes displayed -- Quick file selection - -### ⏮️ Undo/Redo Support -Made a mistake? No problem: -- Undo operations to previous versions -- Redo changes you undid -- Version history tracking -- Jump to any previous state - -### 🎯 Focused Workspace -Everything in one place: -- Clean, uncluttered interface -- Tool settings sidebar -- File preview area -- Results management - ---- - -## How to Use Multi-Tool - -### Getting Started - -1. **Open Multi-Tool** - - Click "Multi-Tool" from the home page (in Recommended Tools) - - Or navigate to it from the tools menu - -2. **Upload Your Files** - - Drag and drop PDFs into the workspace - - Or click to browse and select files - - Upload one or multiple PDFs as needed - -3. **Select a Tool** - - Click the tool selector/menu - - Browse or search for the operation you need - - Tool opens in the sidebar with its settings - -4. **Configure and Process** - - Adjust tool-specific settings - - Select which files to process - - Click "Process" or "Apply" - -5. **Continue Working** - - Result is added to your workspace - - Original file preserved (unless you choose to replace) - - Select another tool to continue - - Build your workflow step by step - ---- - -## Common Workflows - -### Example 1: Document Preparation -**Goal:** Prepare a scanned document for distribution - -1. **Upload** your scanned PDF -2. **OCR** → Make it searchable -3. **Crop** → Remove scanner edges -4. **Compress** → Reduce file size -5. **Add Watermark** → Brand the document -6. **Download** → Save final version - -**Time saved:** No re-uploading between 5 operations! - ---- - -### Example 2: Multi-Document Merger -**Goal:** Combine and enhance multiple PDFs - -1. **Upload** multiple PDF files -2. **Merge** → Combine into one document -3. **Add Page Numbers** → Number all pages -4. **Add Table of Contents** → Improve navigation -5. **Add Password** → Secure the result -6. **Download** → Final protected document - -**Benefit:** All files managed in one workspace - ---- - -### Example 3: Experimentation -**Goal:** Find the best compression settings - -1. **Upload** your PDF -2. **Compress** with low settings → Check quality -3. **Undo** → Return to original -4. **Compress** with medium settings → Compare -5. **Undo** → Try again -6. **Compress** with high settings → Find best balance -7. **Download** preferred version - -**Advantage:** Undo/redo lets you compare results easily - ---- - -### Example 4: Batch Processing -**Goal:** Apply same operations to multiple files - -1. **Upload** 10 PDF files -2. **Rotate** → Fix orientation on all -3. **Crop** → Remove margins from all -4. **Add Watermark** → Brand all documents -5. **Download All** → Get processed batch - -**Efficiency:** Process entire batch without individual uploads - ---- - - -## File Management - -### Adding Files -- **Drag and Drop:** Easiest method - drag PDFs into workspace -- **Browse:** Click "Add Files" or upload button -- **From Previous Operation:** Results automatically added to workspace - -### Organizing Files -- **Select:** Click to select files for specific operations -- **Multi-Select:** Hold Ctrl/Cmd to select multiple files - -### Removing Files -- **Individual:** Click X or delete button on file thumbnail -- **Clear All:** Use "Clear Files" button to remove everything -- **Auto-Clear:** Files clear when you close the browser (configurable) - -### Storage Information -- **Used Space:** See how much browser storage you're using -- **Remaining Space:** Check available space -- **Per-File Size:** Each file shows its size -- **Total Size:** See total workspace usage - ---- - -## Workspace Features - -### File Previews -- **Thumbnails:** First page thumbnail for each PDF -- **Quick Preview:** Click thumbnail for larger preview -- **Page Count:** Shows number of pages per file -- **File Info:** See file size and last modified time - -### Settings and Options -- **Tool Settings:** Configure each operation's parameters -- **Apply to Selected:** Process only selected files -- **Apply to All:** Process entire workspace -- **Batch Mode:** Process multiple files with same settings - ---- - -## Best Practices - -### 1. Organize Before Starting -- Name your files descriptively before uploading -- Group related files together -- Plan your workflow sequence - -### 2. Work Progressively -- Start with one file to test settings -- Apply same settings to batch once confirmed -- Build complexity gradually - -### 3. Use Undo Liberally -- Try different settings and compare -- Don't worry about mistakes -- Experiment freely with undo safety net - -### 4. Manage Storage -- Clear completed projects regularly -- Download important results immediately -- Monitor storage usage indicator -- Use desktop app for unlimited storage - -### 5. Save Intermediate Results -- Download important intermediate versions -- Don't rely on browser storage long-term -- Clear files before closing on shared computers - -### 6. Leverage File Persistence -- Upload all related files at once -- Use them across multiple operations -- Avoid re-uploading unnecessarily - ---- - -## Tips and Tricks - -### Speed Up Your Workflow -- **Quick Tool Switch:** Use search to find tools quickly -- **Favorite Tools:** Frequently used tools appear first -- **Batch Operations:** Select multiple files and process at once -- **Undo/Redo:** Use toolbar buttons to revert or reapply changes - -### Avoid Common Issues -- **Storage Full:** Clear old files before uploading large PDFs -- **Lost Files:** Download important results before clearing storage -- **Performance:** Close and reopen Multi-Tool if it becomes slow -- **Browser Refresh:** Save work before refreshing (files may clear) - -### Advanced Techniques -- **Version Branching:** Keep multiple versions to try different approaches -- **Quality Comparison:** Compress at different levels and compare -- **Template Workflows:** Develop standard sequences for repetitive tasks -- **Batch Consistency:** Use same settings across document sets +1. **Upload** - Drag and drop one or more PDFs into the workspace +2. **Select pages** - Click thumbnails or use select all / page number input +3. **Edit** - Rotate, reorder, delete, split, or insert as needed +4. **Export** - Save changes to download the full PDF, or export selected pages only --- ## Multi-Tool vs. Individual Tools vs. Automate -### Use Multi-Tool When: -✅ Working with multiple related operations -✅ Need flexibility to adjust on the fly -✅ Experimenting with different settings -✅ Want visual feedback at each step -✅ Processing a few files with various operations - -### Use Individual Tools When: -✅ Single, simple operation needed -✅ Quick one-off task -✅ Don't need file persistence -✅ Processing one file, one time - -### Use Automate When: -✅ Same workflow repeated frequently -✅ Predictable, consistent operations -✅ Automated folder processing -✅ No manual intervention needed -✅ Large batch processing - ---- - -## Browser Storage and Privacy - -### How It Works -- Files stored in your browser's **local IndexedDB** -- Data never leaves your device until you process -- Only you can access your stored files -- Storage is per-domain (isolated from other sites) - -### Storage Limits -Typical browser limits: -- **Chrome/Edge:** ~10GB or 60% of available disk space -- **Firefox:** ~10GB -- **Safari:** ~1GB (more restrictive) - -### Privacy Controls -- **Clear on Exit:** Configure browser to clear data on close -- **Manual Clear:** Use "Clear Files" button anytime -- **Incognito Mode:** Storage cleared when window closes -- **Desktop App:** Full offline privacy, unlimited storage - -### Security Notes -- Files are **not encrypted** in browser storage -- Don't store highly sensitive documents long-term -- Use desktop app for sensitive work -- Clear storage on shared/public computers - ---- - -## Troubleshooting - -### Files Disappeared -**Possible Causes:** -- Browser cleared storage automatically -- You clicked "Clear Files" -- Browser data was cleared manually -- Switched to incognito mode - -**Solutions:** -- Check Downloads folder (you may have saved them) -- Use desktop app for persistent storage -- Enable "persistent storage" in browser settings - ---- - -### Out of Storage Space -**Symptoms:** Can't upload new files, error messages - -**Solutions:** -1. Clear old/completed projects -2. Download and delete large files -3. Use desktop app for large projects -4. Compress files before uploading - ---- - -### Multi-Tool Running Slowly -**Symptoms:** Lag, freezing, slow response - -**Solutions:** -1. Clear unused files from workspace -2. Close other browser tabs -3. Restart browser -4. Use desktop app for better performance -5. Reduce number of files in workspace - ---- - -### Can't Find a Tool -**Symptoms:** Tool missing from Multi-Tool - -**Possible Reasons:** -- Tool has dedicated interface (Compare, Automate, Sign) -- Tool has been disabled by administrator -- Search for tool name to locate it - ---- - -## Desktop App vs. Browser Multi-Tool - -### Browser Multi-Tool -**Pros:** -- No installation needed -- Access from any device -- Automatic updates -- Web-based convenience - -**Cons:** -- Storage limits (~1-10GB) -- Files may be cleared -- Requires internet for processing -- Browser-dependent performance - -### Desktop App Multi-Tool -**Pros:** -- Unlimited storage -- True persistent files -- Completely offline capable -- Native performance -- Files in your file system - -**Cons:** -- Requires installation -- Device-specific -- Manual updates - -**Recommendation:** Desktop app for serious work, browser for quick tasks +| | Multi-Tool | Individual Tools | Automate | +|---|---|---|---| +| Multiple operations | Yes | No | Yes | +| Visual feedback | Yes | Limited | No | +| Repeatable workflow | No | No | Yes | +| Folder watching | No | No | Yes | --- ## Related Documentation -- **[Recommended Tools](./Recommended-Tools.md)** - Other frequently used tools - **[Automate (Pipeline)](./Features%20Pipeline.md)** - Automated workflows - **[Complete Tool Reference](./Functionality.md)** - All available tools -- **[Desktop App Installation](../Installation/Windows.md)** - Get unlimited storage - ---- - -## Frequently Asked Questions - -### Can I save my Multi-Tool workspace? -Not directly, but you can: -- Download all processed files -- Use Automate to save operation sequences -- Desktop app keeps files in your file system - -### How long are files stored? -- Until you manually clear them -- Until browser storage is cleared -- Until browser closes (if configured that way) -- Desktop app: indefinitely in your file system - -### Can I access files from another device? -No, browser storage is device-specific. Options: -- Download files and transfer them -- Use cloud storage between devices -- Self-host Stirling PDF on your network - -### Does Multi-Tool work offline? -- **Browser:** No, requires server connection for processing -- **Desktop App:** Yes, completely offline capable - -### Can I process multiple files at once? -Yes! Select multiple files and most operations will process them in batch. - ---- - -## Summary - -Multi-Tool is your **PDF command center** in Stirling PDF V2: -- 📁 Upload once, use everywhere -- 🔄 Chain unlimited operations -- ⏮️ Undo/redo for experimentation -- 👁️ Visual file management -- 🚀 Efficient multi-step workflows - -**Perfect for:** Complex PDF tasks, multi-step operations, batch processing, and exploratory work. - -Ready to supercharge your PDF workflow? Open Multi-Tool and experience the V2 difference! diff --git a/docs/Functionality/OCR.md b/docs/Functionality/OCR.md index b2b6210a..040a7afa 100644 --- a/docs/Functionality/OCR.md +++ b/docs/Functionality/OCR.md @@ -9,300 +9,79 @@ description: Make scanned PDFs searchable and editable with OCR **Tool ID:** `ocr-pdf` -Make scanned PDFs searchable and editable by recognizing text in images. Stirling PDF's OCR tool uses Tesseract OCR engine to extract text from image-based PDFs and convert them into searchable, selectable documents. +Make scanned PDFs searchable and selectable by recognizing text in images. Uses the Tesseract OCR engine. --- -## What is OCR? - -OCR (Optical Character Recognition) is technology that recognizes text within images and converts it into actual, selectable text. This makes scanned documents searchable, editable, and accessible. - -### When You Need OCR +## When You Need OCR - Scanned paper documents (no text layer) - Photos of documents or whiteboards -- Screenshots of text -- Image-only PDFs -- PDFs where you can't select or search text +- Image-only PDFs where you can't select or search text --- -## How to Use OCR +## How to Use 1. **Upload Your PDF** - Select a scanned or image-based PDF 2. **Select Language(s)** - Choose the language(s) in your document -3. **Configure Options** - Adjust OCR settings (optional) -4. **Process** - Run OCR on the document +3. **Configure Options** - Adjust OCR mode and preprocessing (optional) +4. **Process** - Run OCR 5. **Download** - Get your searchable PDF --- -## Language Support - -Stirling PDF supports OCR in **100+ languages** including: - -### Common Languages -- **English** - eng -- **Spanish** - spa -- **French** - fra -- **German** - deu -- **Italian** - ita -- **Portuguese** - por -- **Russian** - rus -- **Chinese (Simplified)** - chi_sim -- **Chinese (Traditional)** - chi_tra -- **Japanese** - jpn -- **Korean** - kor -- **Arabic** - ara -- **Hindi** - hin -- **Dutch** - nld -- **Polish** - pol -- **Turkish** - tur -- **Vietnamese** - vie -- **Thai** - tha - -### Multiple Languages - -If your document contains multiple languages, you can select multiple language packs for better accuracy. - -**Example:** A document with English and Spanish text should have both `eng` and `spa` selected. - ---- - -## OCR Options - -### Layout Preservation - -**Options:** -- **Preserve Original Layout** - Maintains original page structure, formatting, and layout -- **Simple Text Layer** - Adds searchable text without preserving complex formatting -- **Clean Text Only** - Extracts text without any layout preservation - -**Recommendation:** Use "Preserve Original Layout" for documents where visual structure matters (forms, tables, multi-column layouts). - -### OCR Quality Settings - -**Options:** -- **Fast** - Quick processing, good for clean scans -- **Balanced** - Good quality with reasonable speed (recommended) -- **Best** - Maximum accuracy, slower processing - -### Preprocessing Options - -Improve OCR accuracy by preprocessing images: - -- **Auto-rotate** - Automatically detect and correct page orientation -- **Deskew** - Fix slightly tilted/skewed scans -- **Despeckle** - Remove noise and artifacts from scans -- **Remove Background** - Clean up paper texture and shadows -- **Enhance Contrast** - Improve readability of faded text - -**Tip:** For poor quality scans, enable multiple preprocessing options. - ---- - -## Best Practices - -### For Best OCR Results - -1. **Use high-quality scans** - - 300 DPI or higher recommended - - Higher resolution = better accuracy - - Minimum 150 DPI for acceptable results - -2. **Clean, clear images** - - High contrast between text and background - - Minimal shadows or stains - - Sharp focus, not blurry - -3. **Correct orientation** - - Text should be right-side up - - Use auto-rotate if unsure - -4. **Select correct language** - - Choose all languages present in document - - Wrong language = poor accuracy - -5. **Preprocess poor scans** - - Enable deskew for tilted pages - - Use despeckle for noisy scans - - Enhance contrast for faded text - -### Document Types - -**Works Best With:** -- ✅ Scanned documents (text documents, contracts, letters) -- ✅ Photos of documents taken with good lighting -- ✅ Clean screenshots of text -- ✅ Printed text (books, magazines, reports) - -**Challenging Cases:** -- ⚠️ Handwritten text (limited accuracy) -- ⚠️ Stylized or decorative fonts -- ⚠️ Very small text (< 8pt font) -- ⚠️ Low resolution images -- ⚠️ Heavily compressed or artifacted images - ---- - -## Common Issues - -### "No text recognized" - -**Possible Causes:** -- Wrong language selected -- Image quality too poor -- Text too small or blurry -- Extreme skew/rotation - -**Solutions:** -- Verify correct language pack selected -- Use higher quality scan -- Enable preprocessing options -- Check document orientation - -### "Poor accuracy / Garbled text" - -**Possible Causes:** -- Low quality scan -- Wrong language selected -- Unusual font or formatting -- Background interference - -**Solutions:** -- Increase scan resolution -- Select multiple language packs -- Enable despeckle and contrast enhancement -- Clean up document before scanning - -### "Processing takes too long" - -**Possible Causes:** -- Large document (many pages) -- High resolution images -- "Best" quality setting -- Multiple preprocessing options - -**Solutions:** -- Process in smaller batches -- Use "Balanced" quality setting -- Reduce resolution if very high -- Disable unnecessary preprocessing - ---- - -## Technical Details - -### OCR Engine - -Stirling PDF uses **Tesseract OCR**, an industry-standard open-source OCR engine originally developed by HP and now maintained by Google. +## Options -**Key Features:** -- Over 100 languages supported -- Multiple output formats -- Layout analysis and preservation -- Character and word confidence scores +| Option | Values | Description | +|--------|--------|-------------| +| **Languages** | Select from installed packs | Must match the languages in your document. Select multiple if needed | +| **OCR Mode** | Auto (default), Force, Strict | Auto skips pages that already have text. Force re-OCRs everything. Strict aborts if any text is found | +| **Compatibility Mode** | On/Off | Uses sandwich PDF format for better compatibility with older software (larger files) | -### Processing Steps +### Advanced Options -1. **Image Analysis** - Detect page layout and text regions -2. **Preprocessing** - Apply selected image enhancements -3. **Text Recognition** - Recognize characters using language models -4. **Layout Reconstruction** - Preserve original formatting -5. **PDF Generation** - Create searchable PDF with text layer +| Option | Description | +|--------|-------------| +| **Deskew** | Automatically straighten tilted/skewed pages | +| **Clean Input** | Preprocess by removing noise and enhancing contrast for better recognition | +| **Clean Output** | Post-process the final PDF to remove OCR artifacts | +| **Create Text File** | Generate a separate .txt file with the extracted text (output as ZIP) | -### Output Format - -OCR produces a **PDF with embedded text layer**: -- Original image preserved (visual appearance unchanged) -- Invisible text layer added on top -- Text is searchable and selectable -- Layout matches original document +Advanced options require OCRmyPDF. With Tesseract only, they are ignored. --- -## Configuration - -### Installing Language Packs - -By default, Stirling PDF includes common language packs. To add additional languages: - -**Docker:** -```dockerfile -# Install additional language packs -RUN apt-get update && apt-get install -y \ - tesseract-ocr-ara \ - tesseract-ocr-chi-sim \ - tesseract-ocr-jpn -``` - -**See:** [OCR Configuration Guide](../Configuration/OCR.md) for detailed setup instructions. +## Language Packs -### Environment Variables - -```yaml -# OCR Settings -system: - ocr: - enabled: true - languages: "eng,spa,fra,deu" # Default languages - pageSegmentationMode: auto -``` +Available languages depend on which Tesseract language packs are installed. The default Docker image includes English, German, French, Portuguese, and Chinese Simplified. To add more languages, see the **[OCR Configuration Guide](../Configuration/OCR.md)**. --- -## Use with Other Tools - -### Common Workflows - -**OCR → Convert to Word** -1. Run OCR to make document searchable -2. Use [Convert](./Convert/Convert.md) to export to DOCX -3. Edit document in Word - -**OCR → Search & Redact** -1. Run OCR to add text layer -2. Use search to find sensitive information -3. Use [Redact](./Page-Operations/redact.md) to remove it +## Limitations -**OCR → Extract Data** -1. Run OCR on scanned forms/invoices -2. Use [PDF to CSV](./Convert/Convert.md) to extract tables -3. Import data into spreadsheet - -**Scan → OCR → Compress** -1. Scan documents to PDF -2. Run OCR to make searchable -3. Use [Compress](./Compress.md) to reduce file size +- Handwritten text has limited accuracy +- Stylized/decorative fonts and very small text (< 8pt) are challenging +- For best results, use 300 DPI or higher scans with good contrast --- ## API Usage -Perform OCR programmatically via API: - ```bash -curl -X POST http://stirling-pdf:8080/api/v1/ocr/pdf \ +curl -X POST http://stirling-pdf:8080/api/v1/misc/ocr-pdf \ -F "fileInput=@scanned.pdf" \ - -F "languages=eng+spa" \ - -F "sidecar=false" \ + -F "languages=eng" \ + -F "languages=spa" \ + -F "ocrType=skip-text" \ + -F "ocrRenderType=hocr" \ -F "deskew=true" \ -F "clean=true" \ -F "cleanFinal=true" \ - -F "ocrType=force" \ - -F "ocrRenderType=hocr" \ + -F "sidecar=false" \ -o searchable.pdf ``` -**Parameters:** -- `languages` - Language codes (+ separated) -- `sidecar` - Generate separate text file -- `deskew` - Fix tilted pages -- `clean` - Remove noise -- `cleanFinal` - Final cleanup -- `ocrType` - `skip`, `force`, or `auto` -- `ocrRenderType` - Output format - See [API Documentation](../API.md) for complete endpoint reference. --- @@ -311,20 +90,4 @@ See [API Documentation](../API.md) for complete endpoint reference. - **[Convert](./Convert/Convert.md)** - Convert OCR'd PDFs to Word, text, or other formats - **[Compress](./Compress.md)** - Reduce file size after OCR -- **[Multi-Tool](./Multi-Tool.md)** - Chain OCR with other operations - **[Auto-Rename](./Advanced-Tools#auto-rename)** - Rename files based on OCR'd content - ---- - -## Summary - -Stirling PDF's OCR tool provides: - -✅ **100+ language support** - Recognize text in any language -✅ **Layout preservation** - Maintain original document formatting -✅ **Batch processing** - OCR multiple files at once -✅ **Preprocessing options** - Enhance poor quality scans -✅ **Industry-standard engine** - Tesseract OCR with proven accuracy -✅ **API access** - Automate OCR workflows - -Perfect for digitizing scanned documents, making PDFs searchable, and extracting text from images! diff --git a/docs/Functionality/Read-and-Annotate.md b/docs/Functionality/Read-and-Annotate.md index b347131e..cb84a5ed 100644 --- a/docs/Functionality/Read-and-Annotate.md +++ b/docs/Functionality/Read-and-Annotate.md @@ -9,477 +9,83 @@ description: Interactive PDF viewer with annotation tools for reading and markup **Tool ID:** `read` -The Read & Annotate tool is Stirling PDF V2's interactive PDF viewer and annotation system. Read PDFs directly in your browser while adding comments, highlights, drawings, and other markup - all without leaving the application. +Interactive PDF viewer and annotation system. Read PDFs directly in your browser while adding comments, highlights, drawings, shapes, and other markup. :::tip V2.0 Feature -Built with **[EmbedPDF](https://www.embedpdf.com/)**, an advanced open-source PDF viewer, the Read tool provides a fluid reading and annotation experience with full support for PDF standards. +Built with **[EmbedPDF](https://www.embedpdf.com/)**, an advanced open-source PDF viewer with full support for PDF annotation standards. ::: --- -## What is Read & Annotate? +## Annotation Tools -Read & Annotate is a full-featured PDF viewer that lets you: -- Read PDFs in a clean, focused interface -- Add annotations, comments, and notes -- Highlight and markup text -- Draw freehand on pages -- Add shapes, arrows, and callouts -- Insert text boxes and sticky notes -- Collaborate by marking up documents -- Save annotated PDFs for sharing +### Text Markup +- **Highlight**, **Underline**, **Strikeout**, **Squiggly underline** +- Full color picker and opacity control (10-100%) -Think of it as your digital PDF notepad - read, review, and mark up documents all in one place. +### Drawing +- **Pen** - Freehand drawing with adjustable width (1-12px) +- **Freehand Highlighter** - Width (1-20px) and opacity control ---- - -## Key Features - -### 📖 Full PDF Viewer -Professional reading experience: -- Smooth page scrolling -- Zoom in/out controls -- Full-screen mode -- Page thumbnails for navigation -- Search within document -- Bookmarks and table of contents -- Print from browser - -### ✏️ Text Annotations -Mark up text with ease: -- **Highlight** - Yellow, green, pink, blue highlighters -- **Underline** - Emphasize important text -- **Strikethrough** - Mark text for removal -- **Text Notes** - Add comments anywhere -- **Sticky Notes** - Floating note boxes - -### 🎨 Drawing Tools -Freehand markup capabilities: -- **Pen/Pencil** - Draw freehand -- **Highlighter** - Freehand highlighting -- **Eraser** - Remove drawn annotations -- **Colors** - Full color palette -- **Line Width** - Adjustable thickness -- **Opacity** - Control transparency - -### 📐 Shape Tools -Add structured markup: -- **Lines** - Straight lines and arrows -- **Rectangles** - Boxes and frames -- **Circles/Ellipses** - Round shapes -- **Arrows** - Directional indicators -- **Callouts** - Speech bubbles for comments -- **Stamps** - Pre-made approval stamps - -### 💬 Comments and Notes -Collaborative features: -- **Text Comments** - Add detailed feedback -- **Reply Threads** - Respond to annotations -- **Author Attribution** - Track who added what -- **Timestamp** - See when added -- **Comment Panel** - List all comments - -### 💾 Save and Export -Keep your work: -- **Save Annotations** - Embedded in PDF -- **Download** - Get annotated PDF -- **Standard Format** - Compatible with other PDF readers -- **Preserve Original** - Keep original unchanged option - ---- - -## How to Use Read & Annotate - -### Opening a PDF - -1. **Navigate to Read Tool** - - Click "Read" from home page (Recommended Tools) - - Or select from tools menu +### Shapes +- **Square**, **Circle**, **Line**, **Arrow**, **Polyline**, **Polygon** +- Independent stroke and fill color, border width (0-12px), opacity -2. **Upload Your PDF** - - Drag and drop PDF into viewer - - Or click to browse and select file - - PDF opens in reading mode +### Comments & Text +- **Text Comment** - Attach comments to any location +- **Insert Text** / **Replace Text** - Mark text insertions and replacements +- **Text Box** - Free text with font size, alignment, and background color +- **Note** - Sticky notes with background color -3. **Start Reading** - - Scroll through pages - - Use zoom controls as needed - - Navigate with thumbnail panel +### Stamps & Signatures +- **Stamp** - Add images/photos +- **Signature Stamp** - Signature images +- **Signature Ink** - Handwritten signatures ---- - -## Annotation Tools Guide - -### Highlighting Text - -**How to highlight:** -1. Click the Highlight tool in toolbar -2. Select highlight color (yellow, green, pink, blue) -3. Click and drag over text you want to highlight -4. Release to apply -5. Highlight appears immediately - -**Tips:** -- Hold Shift to highlight across multiple lines -- Double-click to highlight entire word -- Triple-click to highlight entire paragraph -- Change color by clicking highlighted text +### Comment Threads +- Reply threads on any annotation +- Author attribution and timestamps +- Comments sidebar listing all comments grouped by page +- Click to navigate to the source annotation --- -### Adding Comments - -**How to add comments:** -1. Click the Comment/Note tool -2. Click where you want to add comment -3. Type your comment in the popup box -4. Click "Save" or press Enter -5. Comment icon appears on page +## Viewer Features -**Comment Features:** -- **Edit:** Click comment icon to edit text -- **Delete:** Right-click → Delete -- **Move:** Drag comment icon to reposition -- **Reply:** Click to add threaded replies -- **Color-Code:** Assign colors to organize - ---- - -### Drawing Freehand - -**How to draw:** -1. Select Pen/Pencil tool from toolbar -2. Choose color and line thickness -3. Click and drag to draw on page -4. Release when finished -5. Repeat for additional drawings - -**Drawing Controls:** -- **Undo:** Use undo button to undo last stroke -- **Eraser:** Switch to eraser to remove parts -- **Opacity:** Adjust for transparent overlay -- **Smooth:** Lines auto-smoothed for clean look - ---- - -### Adding Shapes - -**How to add shapes:** -1. Select shape tool (Rectangle, Circle, Arrow, etc.) -2. Choose border color and fill -3. Click and drag to create shape -4. Release to place -5. Drag handles to resize - -**Shape Options:** -- **Border:** Color and thickness -- **Fill:** Solid color or transparent -- **Style:** Solid, dashed, or dotted lines -- **Resize:** Drag corner handles -- **Rotate:** Rotate handle for angles - ---- - -### Text Boxes - -**How to add text boxes:** -1. Select Text Box tool -2. Click where you want text -3. Type your text -4. Adjust font, size, and color -5. Click outside box when done - -**Text Formatting:** -- **Font:** Choose from available fonts -- **Size:** Adjust text size -- **Color:** Any color for text -- **Alignment:** Left, center, right -- **Bold/Italic:** Style options - ---- - -## Navigation Features - -### Page Navigation -- **Scroll:** Mouse wheel or trackpad -- **Arrow Keys:** Up/down for pages -- **Page Numbers:** Jump to specific page -- **Thumbnails:** Click thumbnail to jump -- **Bookmarks:** Use PDF bookmarks if present - -### Zoom Controls -- **Zoom In:** + button or Ctrl/Cmd++ -- **Zoom Out:** - button or Ctrl/Cmd+- -- **Fit Width:** Fit page width to screen -- **Fit Height:** Fit page height to screen -- **Actual Size:** 100% zoom -- **Custom:** Enter specific percentage - -### View Modes -- **Single Page:** One page at a time -- **Continuous:** Scrolling multiple pages -- **Two-Page Spread:** Side-by-side pages -- **Full Screen:** Distraction-free reading -- **Presentation:** Slideshow mode - ---- - -## Collaboration Features - -### Multi-User Annotations -When multiple people review the same document: -- **Author Names:** Each annotation shows who created it -- **Timestamps:** See when annotations were added -- **Color Coding:** Assign colors to different reviewers -- **Thread Comments:** Reply to others' comments -- **Version Tracking:** Compare different annotated versions - -### Sharing Annotated PDFs -Your annotations are embedded in standard PDF format: -- ✅ **Compatible:** Opens in Adobe Acrobat, Foxit, etc. -- ✅ **Preserved:** Annotations travel with the file -- ✅ **Editable:** Others can add more annotations -- ✅ **Professional:** Standard PDF annotation format +- Page navigation (first/prev/next/last, direct page jump) +- Zoom in/out with manual percentage entry +- Single page and dual-page spread modes +- Thumbnail sidebar, bookmark sidebar, attachment sidebar +- Full-text search (Ctrl+F) with result highlighting and navigation +- Print (Ctrl+P) --- ## Keyboard Shortcuts -### Navigation -| Shortcut | Action | -|----------|--------| -| **Arrow Keys** | Navigate pages | -| **Page Up/Down** | Jump pages | -| **Home** | First page | -| **End** | Last page | -| **Ctrl/Cmd + F** | Find/Search | - -### Zoom -| Shortcut | Action | -|----------|--------| -| **Ctrl/Cmd + +** | Zoom in | -| **Ctrl/Cmd + -** | Zoom out | -| **Ctrl/Cmd + 0** | Reset zoom | -| **Ctrl/Cmd + Mouse Wheel** | Zoom in/out | - -### Tools | Shortcut | Action | |----------|--------| -| **Ctrl/Cmd + Z** | Undo annotation | -| **Ctrl/Cmd + Y** | Redo annotation | -| **H** | Highlight tool | -| **T** | Text tool | -| **P** | Pen tool | -| **Delete** | Remove selected annotation | - -### View -| Shortcut | Action | -|----------|--------| -| **F11** | Full screen | -| **Esc** | Exit full screen | -| **Ctrl/Cmd + Shift + T** | Toggle thumbnails | - ---- - -## Annotation Properties - -### Customization Options -Every annotation can be customized: -- **Color:** Choose from full color palette -- **Opacity:** Make transparent or opaque -- **Border Width:** Thick or thin lines -- **Font:** Text annotation font styles -- **Author:** Set your name for attribution -- **Date:** Timestamp of creation - -### Editing Annotations -Modify existing annotations: -- **Select:** Click any annotation to select -- **Move:** Drag to reposition -- **Resize:** Drag handles to resize -- **Edit Text:** Click to edit comment text -- **Change Color:** Select and change color -- **Delete:** Select and press Delete key - ---- - -## Best Practices - -### For Effective Reviewing -1. **Color Code:** Use consistent colors for different types of feedback -2. **Be Specific:** Add detailed comments, not just highlights -3. **Use Shapes:** Circle important areas, arrow to specific elements -4. **Layer Annotations:** Use different tools for different purposes -5. **Save Often:** Don't lose your markup work - -### For Clear Communication -1. **Descriptive Comments:** Write clear, actionable feedback -2. **Numbered Points:** Number comments for reference in discussions -3. **Priority Levels:** Use colors to indicate urgency -4. **Location Markers:** Use arrows and shapes to be precise -5. **Summary Notes:** Add overall comment at end - -### For Organization -1. **Naming Convention:** Save annotated PDFs with descriptive names -2. **Version Control:** Include version numbers in filenames -3. **Date Stamps:** Note review date in filename or comment -4. **Backup Copies:** Keep original un-annotated version -5. **Export Comments:** List all comments before final review +| **Ctrl+F** | Search | +| **Ctrl+P** | Print | +| **Ctrl+S** | Save changes | +| **Ctrl+Z** | Undo | +| **Ctrl+Shift+Z / Ctrl+Y** | Redo | +| **Ctrl++/-** | Zoom in/out | +| **Ctrl+0** | Fit to width | +| **Home / End** | First / last page | +| **PageUp / PageDown** | Previous / next page | --- -## Saving and Exporting - -### Save Options -- **Save Annotations:** Embeds annotations in PDF file -- **Flatten Annotations:** Merge annotations into pages (permanent) -- **Export Comments:** Extract comments to separate file -- **Print with Annotations:** Annotations visible when printed +## Saving -### Download Formats -- **PDF with Annotations:** Standard annotated PDF -- **Flattened PDF:** Annotations permanently merged -- **Comment Summary:** Text file of all comments - -### File Management -- **Auto-Save:** Annotations saved automatically in browser -- **Manual Save:** Click "Save" to download annotated PDF -- **Clear Browser Storage:** Remember to download before clearing -- **Desktop App:** Saves directly to your file system - ---- - -## Compatibility - -### Annotation Standards -Stirling PDF uses standard PDF annotation formats: -- ✅ **Adobe Acrobat** - Full compatibility -- ✅ **Foxit Reader** - All annotations supported -- ✅ **PDF-XChange** - Complete support -- ✅ **macOS Preview** - Most annotations visible -- ✅ **Other PDF Readers** - Standard format supported - -### Limitations -Some advanced features may not work everywhere: -- Complex callouts might appear as simple shapes -- Custom colors may render slightly differently -- Font choices limited by reader's available fonts - ---- - -## Troubleshooting - -### Annotations Not Saving -**Solution:** -- Click "Save" button to download annotated PDF -- Don't rely on browser storage alone -- Check browser isn't blocking downloads -- Try desktop app for automatic saving - -### Can't Select Text to Highlight -**Possible Causes:** -- PDF is scanned image (no text layer) -- Text is in an image or graphic -- PDF has security restrictions - -**Solutions:** -- Run OCR first to add text layer -- Use freehand highlighter instead -- Check PDF permissions - -### Slow Performance with Many Annotations -**Solutions:** -- Flatten annotations to improve performance -- Split large PDFs into sections -- Use desktop app for better performance -- Clear browser cache - -### Annotations Lost After Closing -**Cause:** Didn't download annotated PDF before closing - -**Prevention:** -- Always download/save annotated PDF -- Don't rely on browser storage long-term -- Use desktop app for persistent files - ---- - -## Read Tool vs. Other Viewers - -### vs. Adobe Acrobat Reader -**Stirling PDF Read:** -- ✅ No installation needed (browser) -- ✅ Integrated with other Stirling tools -- ✅ Open source and free -- ❌ Fewer advanced features -- ❌ Browser-dependent - -**Adobe Acrobat:** -- ✅ More advanced features -- ✅ Native application -- ✅ Industry standard -- ❌ Requires installation -- ❌ Paid features - -### vs. Browser Default PDF Viewer -**Stirling PDF Read:** -- ✅ Full annotation tools -- ✅ Save annotations in PDF -- ✅ Professional markup options -- ✅ Integrated with PDF processing - -**Browser Viewer:** -- ✅ Instant opening -- ❌ Limited or no annotations -- ❌ Basic viewing only - ---- - -## Desktop App vs. Browser - -### Browser Read Tool -**Pros:** -- No installation -- Access anywhere -- Automatic updates - -**Cons:** -- Must download to save -- Browser storage limits -- Requires internet - -### Desktop App Read Tool -**Pros:** -- Saves directly to disk -- Better performance -- Offline capable -- Larger files supported - -**Cons:** -- Requires installation -- Device-specific +- **Save Changes** button or Ctrl+S to apply annotations +- Undo/redo history available before saving +- Annotations are embedded in standard PDF format and compatible with Adobe Acrobat, Foxit Reader, PDF-XChange, and macOS Preview --- ## Related Documentation -- **[Multi-Tool](./Multi-Tool.md)** - Workbench for multiple operations -- **[Sign PDFs](../Functionality/Security/Security.md)** - Add signatures -- **[Recommended Tools](./Recommended-Tools.md)** - Other top tools -- **[Desktop Installation](../Installation/Windows.md)** - Get desktop app - ---- - -## Summary - -The Read & Annotate tool transforms Stirling PDF into a powerful PDF review platform: - -- 📖 **Full-featured viewer** - Professional reading experience -- ✏️ **Complete annotation tools** - Highlights, comments, drawings, shapes -- 💬 **Collaboration ready** - Standard format, multi-user support -- 💾 **Save and share** - Annotated PDFs compatible everywhere -- 🚀 **Integrated workflow** - Part of Stirling PDF V2 ecosystem - -**Perfect for:** Document review, contract markup, student notes, design feedback, form filling, and collaborative editing. - -Ready to start annotating? Open the Read tool and mark up your first PDF! +- **[Multi-Tool](./Multi-Tool.md)** - Page editing workspace +- **[Sign PDFs](./Security/Sign.md)** - Add signatures diff --git a/docs/Functionality/Recommended-Tools.md b/docs/Functionality/Recommended-Tools.md index a5f22044..ff5ad80e 100644 --- a/docs/Functionality/Recommended-Tools.md +++ b/docs/Functionality/Recommended-Tools.md @@ -2,12 +2,12 @@ sidebar_position: 1 id: Recommended-Tools title: Recommended Tools -description: The 7 most commonly used PDF tools in Stirling PDF V2 +description: The most commonly used PDF tools in Stirling PDF --- # Recommended Tools -These are the **7 most frequently used PDF operations** in Stirling PDF, prominently featured for quick access. Perfect for everyday PDF tasks. +The most frequently used PDF operations, prominently featured on the home page for quick access. --- @@ -15,22 +15,9 @@ These are the **7 most frequently used PDF operations** in Stirling PDF, promine **Tool ID:** `multiTool` -A powerful workbench interface that allows you to chain multiple PDF operations together in sequence without re-uploading files between steps. +Page editor workspace - upload PDFs once and chain multiple page operations (rotate, reorder, delete, split) without re-uploading. -### What it does -- Upload PDFs once and use them across multiple operations -- Chain operations together (e.g., merge → compress → add watermark) -- See thumbnail previews of your files -- Switch between different tools seamlessly -- All processing happens in a single session - -### Perfect for -- Complex multi-step PDF workflows -- Working with the same file across different operations -- Experimenting with different settings -- Batch processing with multiple tools - -**📖 [Read the complete Multi-Tool Guide →](./Multi-Tool.md)** for detailed workflows, tips, and advanced features. +**[Multi-Tool Guide →](./Multi-Tool.md)** --- @@ -38,24 +25,7 @@ A powerful workbench interface that allows you to chain multiple PDF operations **Tool ID:** `merge` -Combine multiple PDF documents into a single unified PDF file. - -### What it does -- Merge 2 or more PDF files into one document -- Rearrange the order of PDFs before merging -- Preview thumbnails of each PDF -- Maintain quality of original documents -- Preserve bookmarks and metadata (optional) - -### Perfect for -- Combining multiple reports into one document -- Merging chapters or sections of a book -- Consolidating scanned documents -- Creating comprehensive document packages - -### Options -- **Sort Order:** Drag and drop to reorder PDFs before merging -- **Metadata:** Choose which source document's metadata to keep +Combine multiple PDF documents into a single file. Drag and drop to reorder before merging. --- @@ -63,22 +33,9 @@ Combine multiple PDF documents into a single unified PDF file. **Tool ID:** `compare` -Compare two PDF documents side-by-side and visually highlight the differences between them. Essential for reviewing document revisions and finding changes. +Compare two PDF documents side-by-side with visual difference highlighting. -### What it does -- Display two PDFs side-by-side for easy comparison -- Highlight text differences (added, removed, modified) -- Visual diff view with color coding -- Navigate between changes easily -- Generate comparison reports - -### Perfect for -- Reviewing document revisions -- Finding changes between contract versions -- Quality assurance and proofreading -- Legal document comparison - -**📖 [Read the complete Compare Guide →](./Compare.md)** for detailed comparison modes, settings, use cases, and best practices. +**[Compare Guide →](./Compare.md)** --- @@ -86,22 +43,9 @@ Compare two PDF documents side-by-side and visually highlight the differences be **Tool ID:** `compress-pdf` -Reduce PDF file size while maintaining acceptable quality for your needs. Stirling PDF's compression tool optimizes images, removes unnecessary data, and applies various compression techniques. - -### What it does -- Significantly reduce PDF file size (10-90% reduction) -- Multiple compression levels available -- Compress images within PDFs -- Remove unnecessary metadata -- Optimize for web or email sharing - -### Perfect for -- Sharing PDFs via email -- Reducing storage requirements -- Faster PDF loading times -- Meeting file size upload limits +Reduce PDF file size (10-90% reduction) with configurable quality levels. -**📖 [Read the complete Compress Guide →](./Compress.md)** for detailed compression options, quality settings, tips, and best practices. +**[Compress Guide →](./Compress.md)** --- @@ -109,66 +53,19 @@ Reduce PDF file size while maintaining acceptable quality for your needs. Stirli **Tool ID:** `convert` -Convert between PDF and 50+ other file formats including images, Office documents, HTML, and more. - -### What it does -- Convert TO PDF from 50+ formats -- Convert FROM PDF to images, Office files, HTML, etc. -- Batch conversion support -- Maintains formatting when possible -- Supports both single and multiple file conversion - -### Supported Formats - -#### To PDF -- **Images:** JPG, PNG, GIF, TIFF, BMP, WebP -- **Office:** DOCX, XLSX, PPTX, DOC, XLS, PPT -- **Web:** HTML files, URLs (website screenshots) -- **Text:** TXT, RTF, Markdown -- **Email:** EML (email to PDF) -- **Comics:** CBZ, CBR - -#### From PDF -- **Images:** JPG, PNG, TIFF, BMP, GIF -- **Office:** DOCX (Word), PPTX (PowerPoint) -- **Web:** HTML, XML -- **Text:** Plain text -- **Archival:** PDF/A -- **Data:** CSV (table extraction) -- **Comics:** CBZ, CBR - -### Perfect for -- Converting scanned images to searchable PDFs (combine with OCR) -- Creating PDFs from Office documents -- Extracting text from PDFs -- Archiving emails as PDFs -- Converting PDFs to editable Word documents - -**Learn more:** [Complete Conversion Guide](./Convert/Convert.md) +Convert between PDF and 50+ file formats including images, Office documents, HTML, and more. Batch conversion supported. + +**[Convert Guide →](./Convert/Convert.md)** --- -## OCR (Optical Character Recognition) +## OCR **Tool ID:** `ocr-pdf` -Make scanned PDFs searchable and editable by recognizing text in images. Stirling PDF's OCR tool uses Tesseract OCR engine to extract text from image-based PDFs. - -### What it does -- Recognize text from scanned documents -- Make image-based PDFs searchable -- Extract text from images within PDFs -- Support for 100+ languages -- Preserve original document layout - -### Perfect for -- Scanned documents and images -- Making old paper documents searchable -- Extracting text from photos of documents -- Creating accessible PDFs from scans -- Enabling copy/paste from scanned PDFs +Make scanned PDFs searchable by recognizing text in images. Supports 100+ languages via Tesseract OCR. -**📖 [Read the complete OCR Guide →](./OCR.md)** for detailed instructions, language support, configuration options, and best practices. +**[OCR Guide →](./OCR.md)** --- @@ -176,80 +73,21 @@ Make scanned PDFs searchable and editable by recognizing text in images. Stirlin **Tool ID:** `redact` -Permanently remove sensitive information from PDF documents with black boxes or white spaces. - -### What it does -- Permanently remove (not just hide) text -- Black out or white out sensitive information -- Automatic redaction based on text patterns -- Manual redaction with draw tool -- Regex pattern support for complex redaction - -### Perfect for -- Removing personal information (PII) -- Redacting confidential data -- Preparing documents for public release -- GDPR/privacy compliance -- Legal document redaction - -### Redaction Methods - -#### Manual Redaction -- Draw boxes over areas to redact -- Preview before applying -- Adjust box size and position -- Choose black or white fill - -#### Automatic Redaction -- Search for text patterns to redact -- Use regex for complex patterns -- Redact all instances automatically -- Preview matches before redacting - -### Common Use Cases -- Social Security Numbers: `\d{3}-\d{2}-\d{4}` -- Phone Numbers: `\(\d{3}\) \d{3}-\d{4}` -- Email Addresses: `[\w\.-]+@[\w\.-]+\.\w+` -- Credit Card Numbers: `\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}` -- Custom text: Any word or phrase - -### Important Notes -- **Redaction is permanent** - original content cannot be recovered -- Always download and verify redacted PDFs -- Test regex patterns before applying to ensure accuracy -- Manual review recommended for sensitive documents - -**Learn more:** [Redaction Guide](./Page-Operations/redact.md) - ---- +Permanently remove sensitive information from PDFs. Supports manual redaction (draw boxes) and automatic redaction (text/regex patterns). -## Why These Tools? - -These 7 tools represent the most common PDF operations that users perform daily: - -1. **Multi-Tool** - Work with multiple operations efficiently -2. **Merge** - Combine documents (one of the most requested features) -3. **Compare** - Review changes and differences -4. **Compress** - Share files easily via email/upload -5. **Convert** - Universal format compatibility -6. **OCR** - Make any document searchable -7. **Redact** - Privacy and security compliance - ---- +**Common patterns:** +- SSN: `\d{3}-\d{2}-\d{4}` +- Phone: `\(\d{3}\) \d{3}-\d{4}` +- Email: `[\w\.-]+@[\w\.-]+\.\w+` -## Quick Access +Redaction is permanent - original content cannot be recovered. -In Stirling PDF V2, these recommended tools are: -- ✨ Featured prominently on the home page -- 🔍 Easier to find in search -- ⭐ Marked with special indicators -- 📱 Optimized for quick access +**[Redaction Guide →](./Page-Operations/redact.md)** --- -## Next Steps +## More Tools -- **Explore more tools:** [Complete Tool Reference](./Functionality.md) -- **Standard tools:** [Security](./Security/Security.md), [Page Operations](./Page-Operations/Page-Operations.md) -- **Advanced features:** [Automation Workflows](./Features%20Pipeline.md) -- **API access:** [API Documentation](../API.md) +- **[All Tools](./Functionality.md)** - Complete tool reference +- **[Advanced Tools](./Advanced-Tools.md)** - Automation, repair, overlay, and more +- **[API Documentation](../API.md)** - Programmatic access diff --git a/docs/Functionality/Security/Certificate-Signing.md b/docs/Functionality/Security/Certificate-Signing.md index d2050ab9..f88cf281 100644 --- a/docs/Functionality/Security/Certificate-Signing.md +++ b/docs/Functionality/Security/Certificate-Signing.md @@ -4,844 +4,269 @@ id: Certificate-Signing title: Certificate Signing description: Sign and validate PDF certificates --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Certificate Signing -Stirling PDF provides comprehensive PDF certificate signing and validation capabilities. Digitally sign PDFs with X.509 certificates and validate existing signatures against trusted certificate chains. - ---- - -## Overview - -**Two main features:** - -1. **Sign PDFs** - Apply digital signatures using certificates -2. **Validate Signatures** - Verify certificate-signed PDFs against trust chains - -**Use Cases:** -- Legal document signing -- Contract verification -- Invoice authentication -- Compliance requirements (eIDAS, etc.) -- Enterprise document workflows +Digitally sign PDFs with X.509 certificates and validate existing signatures against trusted certificate chains. --- ## Signing PDFs -### Methods - -#### 1. Sign with Stirling PDF (Server Certificate) - -**Easiest option** - Use auto-generated server certificate. - -**How it works:** -- Server generates self-signed certificate on first startup -- Certificate persists across restarts -- Users sign PDFs with one click -- No certificate management needed - -**Use cases:** -- Internal documents -- Non-legal signatures -- Quick signing workflows -- Testing and development - -**Steps:** -1. Go to **Certificate Sign** tool -2. Upload PDF -3. Select "Sign with Stirling PDF" -4. Configure signature appearance (optional): - - Position on page - - Size - - Visible or invisible - - Text to display -5. Click Sign -6. Download signed PDF - -**Configuration:** -```yaml -system: - serverCertificate: - enabled: true # Enable auto-generation - organizationName: Stirling-PDF # Certificate org name - validity: 365 # Days until expiration - regenerateOnStartup: false # Keep same cert across restarts -``` - -**Environment Variables:** -```bash -SYSTEM_SERVERCERTIFICATE_ENABLED=true -SYSTEM_SERVERCERTIFICATE_ORGANIZATIONNAME="My Company" -SYSTEM_SERVERCERTIFICATE_VALIDITY=365 -``` - ---- - -#### 2. Sign with Custom Certificate - -**For legal/official documents** - Use your own certificate. - -**Requirements:** -- X.509 certificate in PKCS#12 (.p12) or PEM format -- Private key -- Optional: Certificate chain - -**Steps:** -1. Go to **Certificate Sign** tool -2. Upload PDF -3. Select "Upload Certificate" -4. Upload your certificate file (.p12, .pfx, or .pem) -5. Enter certificate password -6. Configure signature appearance -7. Click Sign -8. Download signed PDF - -**Supported formats:** -- `.p12` / `.pfx` - PKCS#12 (most common) -- `.pem` - PEM-encoded certificate + key -- `.crt` + `.key` - Separate cert and key files - -**Example with openssl:** -```bash -# Generate your own certificate (for testing) -openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 - -# Convert to PKCS#12 for Stirling-PDF -openssl pkcs12 -export -out mycert.p12 -inkey key.pem -in cert.pem -``` - ---- - -#### 3. Server-Managed Custom Certificates - -**For admins** - Provide organization certificate for all users. - -**How to set up:** -1. Place certificate in configs directory: - ```bash - configs/ - └── keystore.p12 - ``` - -2. Configure in settings.yml: - ```yaml - system: - serverCertificate: - enabled: false # Disable auto-generation - ``` - -3. Set certificate password via environment variable: - ```bash - KEYSTORE_PASSWORD=your-password - ``` - -**Users see:** -- "Sign with [Organization Name]" option -- No need to upload certificate -- Consistent signing across organization + + + Easiest option - uses an auto-generated server certificate. No setup needed for users. + + 1. Go to **Certificate Sign** tool + 2. Upload PDF + 3. Select "Sign with Stirling PDF" + 4. Configure signature appearance (optional) + 5. Sign and download + + **Configuration:** + + + + ```yaml + system: + serverCertificate: + enabled: true + organizationName: Stirling-PDF + validity: 365 + regenerateOnStartup: false + ``` + + + ```bash + SYSTEM_SERVERCERTIFICATE_ENABLED=true + SYSTEM_SERVERCERTIFICATE_ORGANIZATIONNAME="My Company" + SYSTEM_SERVERCERTIFICATE_VALIDITY=365 + ``` + + + + + Use your own X.509 certificate (PKCS#12 `.p12`/`.pfx` or PEM format). + + 1. Go to **Certificate Sign** tool + 2. Upload PDF + 3. Select "Upload Certificate" + 4. Upload certificate file and enter password + 5. Configure signature appearance + 6. Sign and download + + ```bash + # Generate a test certificate + openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 + + # Convert to PKCS#12 + openssl pkcs12 -export -out mycert.p12 -inkey key.pem -in cert.pem + ``` + + + Place your organization certificate in the configs directory so all users can sign without uploading their own: + + ```bash + configs/ + └── keystore.p12 + ``` + + ```yaml + system: + serverCertificate: + enabled: false # Disable auto-generation + ``` + + ```bash + KEYSTORE_PASSWORD=your-password + ``` + + Users will see a "Sign with [Organization Name]" option. + + --- ### Signature Appearance -Configure how signature appears on PDF: - -#### Visible Signature - -Signature appears as box on PDF page. - -**Options:** -- **Position:** X/Y coordinates or page location (top-left, center, etc.) -- **Size:** Width and height in points -- **Page:** Which page(s) to sign -- **Text:** Name, date, reason displayed -- **Image:** Optional signature image - -**Example configuration:** -```yaml -Signature: - Position: Bottom-Right - Page: Last - Size: 200x100 points - Display: - - Signer Name - - Sign Date - - Reason: "Approved" -``` - -#### Invisible Signature - -Signature embedded in PDF metadata, not visible. - -**Use cases:** -- Digital timestamping -- Authentication without visual mark -- Multiple signatures on same document - ---- +**Visible:** Appears as a box on the PDF page with configurable position, size, page, and displayed text (name, date, reason). -### Signing Multiple PDFs - -**Batch signing** - Sign multiple PDFs with same certificate. - -**Methods:** - -1. **Multi-Tool:** - - Upload multiple PDFs - - Apply certificate sign operation - - All PDFs signed with same cert - - Download as zip - -2. **Pipeline (Automation):** - ```json - { - "name": "Sign Documents", - "pipeline": [ - { - "operation": "cert-sign", - "parameters": { - "certType": "server", - "reason": "Approved", - "location": "bottom-right" - } - } - ] - } - ``` +**Invisible:** Embedded in PDF metadata only, not visible on the page. --- ## Validating Signatures -### What is Signature Validation? - -Verify that: -- ✅ PDF was signed by claimed certificate -- ✅ Certificate is trusted (in trust chain) -- ✅ Certificate was valid at signing time -- ✅ PDF has not been modified since signing -- ✅ Certificate has not been revoked - -### Trust Chains - -Stirling PDF checks multiple trust sources: - -#### 1. Server-Generated Certificates -```yaml -security: - validation: - trust: - serverAsAnchor: true # Trust server-generated certs -``` - -**Use case:** Trust PDFs signed by your Stirling PDF instance. - ---- - -#### 2. System Trust Store -```yaml -security: - validation: - trust: - useSystemTrust: true # Use OS certificate store -``` - -**What it includes:** -- Operating system's trusted CA certificates -- Certificates added by system administrator -- Standard public CAs (Let's Encrypt, DigiCert, etc.) - -**Use case:** Trust certificates from public certificate authorities. - ---- - -#### 3. Mozilla CA Bundle -```yaml -security: - validation: - trust: - useMozillaBundle: true # Mozilla's curated CA list -``` - -**What it includes:** -- Mozilla's trusted CA certificate bundle -- Regularly updated list of trusted CAs -- Well-maintained, widely trusted - -**Use case:** Standard web trust model for PDFs. - ---- - -#### 4. Adobe Approved Trust List (AATL) -```yaml -security: - validation: - trust: - useAATL: true # Adobe's approved CAs - aatl: - url: https://trustlist.adobe.com/tl.pdf -``` - -**What it includes:** -- Certificate authorities approved by Adobe -- Widely recognized for PDF signing -- Automatically updated from Adobe - -**Use case:** Enterprise PDF workflows, Adobe-signed documents. - ---- - -#### 5. EU Trusted List (EUTL) -```yaml -security: - validation: - trust: - useEUTL: true # EU eIDAS trust list - eutl: - lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml - acceptTransitional: false # Accept transitional CAs -``` - -**What it includes:** -- EU member state trusted service providers -- eIDAS-compliant certificates -- European government and business CAs +Verify that a PDF was signed by the claimed certificate, the certificate is trusted, the PDF hasn't been modified, and the certificate hasn't been revoked. -**Use case:** EU legal documents, eIDAS compliance, government workflows. +### Trust Sources ---- +| Source | Config Key | What It Trusts | +|--------|-----------|----------------| +| Server certificates | `serverAsAnchor` | PDFs signed by your Stirling PDF instance | +| System trust store | `useSystemTrust` | OS-trusted CAs | +| Mozilla CA bundle | `useMozillaBundle` | Mozilla's curated CA list | +| Adobe AATL | `useAATL` | Adobe Approved Trust List | +| EU EUTL | `useEUTL` | EU Trusted List (eIDAS) | ### Revocation Checking -Verify certificate has not been revoked: - -```yaml -security: - validation: - revocation: - mode: ocsp+crl # Options: none, ocsp, crl, ocsp+crl - hardFail: false # Fail validation if revocation check fails -``` - -#### Revocation Methods - -| Method | Description | Speed | Reliability | -|--------|-------------|-------|-------------| -| **none** | No revocation check | Instant | ⚠️ Not recommended | -| **ocsp** | Online Certificate Status Protocol | Fast | ✅ Real-time | -| **crl** | Certificate Revocation List | Slower | ✅ Works offline | -| **ocsp+crl** | Try OCSP, fall back to CRL | Medium | ✅ Best balance | - -#### Hard Fail vs Soft Fail - -**Soft Fail (hardFail: false):** -- ✅ Validation succeeds if revocation check unavailable -- ⚠️ Warning shown: "Could not verify revocation status" -- Use when network reliability uncertain - -**Hard Fail (hardFail: true):** -- ❌ Validation fails if revocation check unavailable -- ✅ Stricter security -- Use for high-security environments - ---- - -### Authority Information Access (AIA) - -Automatically fetch missing intermediate certificates: - -```yaml -security: - validation: - allowAIA: false # Enable AIA certificate fetching -``` - -**What it does:** -- Downloads intermediate certificates from URLs in certificate -- Completes certificate chain automatically -- Makes validation more likely to succeed - -**Security consideration:** -- Disabled by default (security best practice) -- Enable only in controlled environments -- Requires outbound HTTPS access - ---- - -## Configuration Examples - -### Minimal Configuration (Default) - -Works out-of-box for basic signing: +Certificates can be revoked (invalidated) after they're issued - for example if a private key is compromised. Revocation checking lets Stirling PDF verify that a certificate is still valid at the time of use. ```yaml -system: - serverCertificate: - enabled: true - security: validation: - trust: - serverAsAnchor: true - useSystemTrust: true -``` - -**Capabilities:** -- ✅ Sign with server certificate -- ✅ Validate system-trusted signatures -- ✅ No external dependencies - ---- - -### Standard Enterprise Setup - -Balanced security and usability: - -```yaml -system: - serverCertificate: - enabled: true - organizationName: Acme Corp - validity: 365 - -security: - validation: - trust: - serverAsAnchor: true - useSystemTrust: true - useMozillaBundle: true - useAATL: false - allowAIA: false revocation: - mode: ocsp + mode: none # Options: none, ocsp, crl, ocsp+crl hardFail: false ``` -**Capabilities:** -- ✅ Sign with company certificate -- ✅ Validate against multiple trust sources -- ✅ OCSP revocation checking (soft fail) -- ✅ Works in most environments - ---- - -### High-Security Configuration - -Strict validation for regulated industries: - -```yaml -security: - validation: - trust: - serverAsAnchor: false - useSystemTrust: true - useMozillaBundle: true - useAATL: true - useEUTL: true - allowAIA: false - revocation: - mode: ocsp+crl - hardFail: true -``` - -**Capabilities:** -- ✅ Only trust external CAs (not server-generated) -- ✅ Multiple trust sources (AATL + EUTL) -- ✅ Dual revocation checking -- ✅ Hard fail on revocation check failure -- Use for: Finance, legal, government - ---- - -### EU eIDAS Compliance - -For European legal documents: - -```yaml -security: - validation: - trust: - serverAsAnchor: false - useSystemTrust: false - useMozillaBundle: false - useAATL: false - useEUTL: true # Only EU trusted list - eutl: - lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml - acceptTransitional: true - allowAIA: false - revocation: - mode: ocsp+crl - hardFail: true -``` +| Mode | What it does | +|------|-------------| +| `none` | Skip revocation checks entirely | +| `ocsp` | Check in real-time against the certificate authority's server (requires internet) | +| `crl` | Download a list of revoked certificates (can work offline with cached lists) | +| `ocsp+crl` | Try real-time check first, fall back to the list if that fails | -**Capabilities:** -- ✅ eIDAS-compliant validation -- ✅ Only EU member state CAs trusted -- ✅ Strict revocation checking -- Use for: EU contracts, government, regulated industries +**`hardFail`** controls what happens when the revocation check itself fails (e.g. server unreachable): +- `false` (default) - validation passes with a warning +- `true` - validation fails entirely. Use this in high-security environments where you'd rather reject a signature than skip the check. --- -## Using the Tools - -### Certificate Sign Tool - -**Location:** Security → Certificate Sign - -**Features:** -- Upload PDF(s) to sign -- Choose certificate source -- Configure signature appearance -- Batch signing support -- Preview signature location - -**Workflow:** -1. Upload PDF(s) -2. Select certificate: - - Server certificate - - Upload custom certificate - - Use organization certificate (if configured) -3. Configure appearance: - - Visible or invisible - - Position and size - - Text and image - - Page selection -4. Add metadata: - - Reason for signing - - Location - - Contact info -5. Sign and download - ---- - -### Validate Signature Tool - -**Location:** Security → Validate Signature (planned) - -**Features:** -- Upload signed PDF -- Check signature validity -- View certificate details -- Check trust chain -- Verify revocation status - -**Output:** -``` -✅ Signature Valid - -Signer: CN=John Doe, O=Acme Corp -Signed: 2025-01-15 10:30:00 UTC -Certificate: RSA 2048-bit - -Trust Chain: - ✅ Acme Corp Root CA - ✅ Acme Corp Intermediate CA - ✅ John Doe +## Configuration Examples -Revocation: ✅ Not revoked (OCSP) -Document: ✅ Not modified -``` + + + ```yaml + system: + serverCertificate: + enabled: true + + security: + validation: + trust: + serverAsAnchor: true + useSystemTrust: true + ``` + + + ```yaml + system: + serverCertificate: + enabled: true + organizationName: Acme Corp + validity: 365 + + security: + validation: + trust: + serverAsAnchor: true + useSystemTrust: true + useMozillaBundle: true + useAATL: false + allowAIA: false + revocation: + mode: ocsp + hardFail: false + ``` + + + ```yaml + security: + validation: + trust: + serverAsAnchor: false + useSystemTrust: true + useMozillaBundle: true + useAATL: true + useEUTL: true + allowAIA: false + revocation: + mode: ocsp+crl + hardFail: true + ``` + + + ```yaml + security: + validation: + trust: + serverAsAnchor: false + useSystemTrust: false + useMozillaBundle: false + useAATL: false + useEUTL: true + eutl: + lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml + acceptTransitional: true + allowAIA: false + revocation: + mode: ocsp+crl + hardFail: true + ``` + + --- ## API Usage -### Sign PDF via API - -**Endpoint:** `POST /api/v1/security/cert-sign` - -**Example with server certificate:** -```bash -curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \ - -F "fileInput=@document.pdf" \ - -F "certType=server" \ - -F "reason=Approved" \ - -F "location=bottom-right" \ - -F "showSignature=true" \ - -o signed.pdf -``` - -**Example with custom certificate:** -```bash -curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \ - -F "fileInput=@document.pdf" \ - -F "certType=custom" \ - -F "certificateFile=@mycert.p12" \ - -F "password=certpass" \ - -F "reason=Contract Approval" \ - -o signed.pdf -``` + + + ```bash + curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \ + -F "fileInput=@document.pdf" \ + -F "certType=server" \ + -F "reason=Approved" \ + -F "location=bottom-right" \ + -F "showSignature=true" \ + -o signed.pdf + ``` + + + ```bash + curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \ + -F "fileInput=@document.pdf" \ + -F "certType=custom" \ + -F "certificateFile=@mycert.p12" \ + -F "password=certpass" \ + -o signed.pdf + ``` + + + ```bash + curl -X POST http://stirling-pdf:8080/api/v1/security/validate-signature \ + -F "fileInput=@signed.pdf" + ``` + + + +See [API Documentation](../../API.md) for complete endpoint reference. --- -### Validate Signature via API - -**Endpoint:** `POST /api/v1/security/validate-signature` +## Troubleshooting -**Example:** +### "Certificate not trusted" +Enable the appropriate trust source in config, or add your CA certificate to the system trust store: ```bash -curl -X POST http://stirling-pdf:8080/api/v1/security/validate-signature \ - -F "fileInput=@signed.pdf" \ - | jq . -``` - -**Response:** -```json -{ - "valid": true, - "signer": "CN=John Doe, O=Acme Corp", - "signDate": "2025-01-15T10:30:00Z", - "trustChain": [ - "CN=Acme Corp Root CA", - "CN=Acme Corp Intermediate CA", - "CN=John Doe" - ], - "revocationStatus": "not_revoked", - "documentModified": false, - "errors": [] -} +docker cp ca-cert.crt stirling-pdf:/usr/local/share/ca-certificates/ +docker exec stirling-pdf update-ca-certificates ``` ---- - -## Troubleshooting - -### Signature validation fails - -**Symptom:** "Certificate not trusted" error. - -**Solutions:** -1. Enable appropriate trust source: - ```yaml - security: - validation: - trust: - useSystemTrust: true # Or useMozillaBundle, useAATL, etc. - ``` - -2. Add certificate to system trust store: - ```bash - # Copy CA certificate to container - docker cp ca-cert.crt stirling-pdf:/usr/local/share/ca-certificates/ - - # Update trust store - docker exec stirling-pdf update-ca-certificates - ``` - -3. Check certificate chain complete: - - Ensure intermediate certificates included - - Or enable AIA fetching (if secure environment) - ---- - ### Revocation check fails - -**Symptom:** "Unable to check revocation status" warning. - -**Solutions:** -1. Check network access: - - Container needs HTTPS access to OCSP/CRL servers - - Check firewall rules - - Verify DNS resolution - -2. Use soft fail: - ```yaml - security: - validation: - revocation: - hardFail: false # Validation succeeds despite revocation check failure - ``` - -3. Use CRL instead of OCSP: - ```yaml - security: - validation: - revocation: - mode: crl # CRL more reliable in restricted networks - ``` - ---- +Check that the container has HTTPS access to OCSP/CRL servers. Use `hardFail: false` or switch to `crl` mode for restricted networks. ### Server certificate not generated - -**Symptom:** "Sign with Stirling PDF" option not available. - -**Solutions:** -1. Check configuration: - ```yaml - system: - serverCertificate: - enabled: true # Must be enabled - ``` - -2. Check logs for errors: - ```bash - docker logs stirling-pdf | grep -i certificate - ``` - -3. Verify write permissions: - ```bash - # Ensure configs directory writable - docker exec stirling-pdf ls -la /configs/ - ``` - -4. Manually regenerate: - ```yaml - system: - serverCertificate: - regenerateOnStartup: true # Force regeneration - ``` - Restart container, then set back to `false`. - ---- - -### EUTL/AATL not loading - -**Symptom:** Validation fails for EUTL/AATL certificates. - -**Solutions:** -1. Check network access: - ```bash - # Test from container - docker exec stirling-pdf curl -I https://ec.europa.eu/tools/lotl/eu-lotl.xml - docker exec stirling-pdf curl -I https://trustlist.adobe.com/tl.pdf - ``` - -2. Check configuration URLs: - ```yaml - security: - validation: - aatl: - url: https://trustlist.adobe.com/tl.pdf # Verify correct URL - eutl: - lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml - ``` - -3. Check for proxy requirements: - ```yaml - # If behind corporate proxy - system: - proxy: - host: proxy.company.com - port: 8080 - ``` - ---- - -## Security Best Practices - -### For Signing - -1. **Use appropriate certificates:** - - Server certificates: Internal/testing only - - Custom certificates: Legal/official documents - - Organization certificates: Centralized management - -2. **Protect private keys:** - - Use strong passwords for PKCS#12 files - - Store keys securely (not in Docker image) - - Rotate certificates regularly - -3. **Configure appearance:** - - Visible signatures for accountability - - Include signer name, date, reason - - Position consistently across documents - -### For Validation - -1. **Enable appropriate trust sources:** - - System trust: General validation - - AATL: Adobe ecosystem - - EUTL: EU legal documents - - Don't enable all unless needed - -2. **Revocation checking:** - - Always enable for production (at least OCSP) - - Use hard fail for high-security - - Use soft fail for reliability - -3. **AIA fetching:** - - Disable by default (security) - - Only enable in controlled environments - - Monitor network traffic - -4. **Trust chain verification:** - - Verify full chain to root CA - - Don't trust self-signed (except server certs for internal use) - - Check expiration dates +Ensure `SYSTEM_SERVERCERTIFICATE_ENABLED=true` is set. Check logs with `docker logs stirling-pdf | grep -i certificate`. --- -## Legal Considerations - -**Disclaimer:** Stirling PDF provides tools for PDF signing and validation. Legal validity depends on jurisdiction and use case. - -### When Certificates Are Legally Binding - -**Generally accepted:** -- ✅ Certificates from trusted CAs (AATL, EUTL) -- ✅ eIDAS-qualified certificates (EU) -- ✅ Certificates with proof of identity verification -- ✅ Proper timestamping - -**May not be legally binding:** -- ⚠️ Self-signed certificates (server-generated) -- ⚠️ Certificates without identity verification -- ⚠️ Expired certificates at signing time - -### Compliance - -**EU eIDAS:** -- Use EUTL trust list -- eIDAS-qualified certificates -- Qualified timestamping -- Long-term validation (LTV) - -**US ESIGN Act:** -- Consent to electronic signatures -- Record retention requirements -- Identity verification - -**Consult legal counsel** for your specific requirements. - ---- - -## Learn More - -**Configuration:** -- [System and Security Settings](../../Configuration/System%20and%20Security#signature-validation) - Technical configuration details -- [Extra Settings](../../Configuration/Extra-Settings) - All certificate-related configuration options - -**Migration:** -- [Settings Changes](../../Migration/Settings-Changes#pdf-signature-validation) - V2 new settings -- [New Features](../../Migration/New-Features#-pdf-signature-validation) - Feature overview - -**Related Tools:** -- [Sign](./Security.md) - Handwritten/image signatures -- [Add Password](./Security.md) - PDF encryption -- [Permissions](./Security.md) - Access control - ---- +## Related -## Summary - -**Stirling PDF certificate signing provides:** - -✅ **Easy signing** - Server certificates work out-of-box -✅ **Custom certificates** - Use your own for legal documents -✅ **Organization certificates** - Centralized cert management -✅ **Comprehensive validation** - Multiple trust sources -✅ **Revocation checking** - OCSP and CRL support -✅ **EU compliance** - eIDAS/EUTL support -✅ **Flexible configuration** - From basic to enterprise -✅ **API access** - Automate workflows - -**Perfect for:** -- Internal document workflows -- Legal document signing -- Contract management -- Invoice verification -- Compliance requirements -- Enterprise automation +- [System and Security Settings](../../Configuration/System%20and%20Security#signature-validation) +- [Sign (Handwritten)](./Sign.md) +- [Settings Changes (V2)](../../Migration/Settings-Changes#pdf-signature-validation) diff --git a/docs/Functionality/Security/Security.md b/docs/Functionality/Security/Security.md index 426eb46e..db3d10e4 100644 --- a/docs/Functionality/Security/Security.md +++ b/docs/Functionality/Security/Security.md @@ -93,58 +93,6 @@ security: --- -## CORS Configuration - -For split deployments where frontend and backend are on different domains, configure Cross-Origin Resource Sharing (CORS). - -### What is CORS? - -CORS allows your frontend (e.g., `https://pdf.example.com`) to communicate with a backend on a different domain (e.g., `https://api.example.com`). - -### Configuration - -```yaml -system: - corsAllowedOrigins: - - 'https://pdf.example.com' - - 'https://pdf.internal.company.com' -``` - -**Environment Variable:** -```bash -SYSTEM_CORSALLOWEDORIGINS=https://pdf.example.com,https://pdf.internal.company.com -``` - -### Use Cases - -- **Split Deployment** - Separate frontend and backend containers -- **CDN Distribution** - Serve frontend from CDN, backend from server -- **Multiple Frontends** - One backend serving multiple frontend instances -- **Development** - Frontend dev server communicating with backend - -### Security Considerations - -**✅ Best Practices:** -- Only allow specific, trusted origins -- Never use wildcard (`*`) in production -- Use HTTPS for all origins -- Verify origin headers server-side - -**⚠️ Common Mistakes:** -```yaml -# DON'T: Allow all origins (insecure) -corsAllowedOrigins: ['*'] - -# DO: Specify exact origins -corsAllowedOrigins: ['https://pdf.example.com'] -``` - -**Learn more:** -- [Split Deployment Configuration](../../Configuration/System%20and%20Security#cors-configuration) -- [Docker Split Mode](../../Installation/Docker%20Install#split-deployment-advanced-users) - ---- - ## Related Configuration For advanced security configuration, see: diff --git a/docs/Functionality/Security/Sign.md b/docs/Functionality/Security/Sign.md index bc7428d2..b2cae41d 100644 --- a/docs/Functionality/Security/Sign.md +++ b/docs/Functionality/Security/Sign.md @@ -4,6 +4,8 @@ id: Sign title: Sign PDF (Handwritten Signatures) description: Add handwritten, text, or image signatures to PDFs --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Sign PDF (Handwritten Signatures) @@ -13,79 +15,39 @@ Add handwritten signatures, text signatures, or image-based signatures to PDF do --- -## What is PDF Signing? - -There are two types of PDF signatures: - -### Handwritten/Visual Signatures (This Tool) -- Draw your signature with mouse/touchscreen -- Add signature as text (typed name) -- Upload signature image (PNG, JPG) -- Visual appearance only -- Non-cryptographic - -**Use For:** Signing forms, contracts, letters where a visual signature is needed. - -### Digital/Certificate Signatures (Different Tool) -- Cryptographic signatures using certificates -- Proves identity and document integrity -- Cannot be forged -- Legally binding in many jurisdictions - -**Use For:** Legal documents, contracts requiring authentication, compliance requirements. - -**Learn More:** [Certificate Signing Guide](./Certificate-Signing) +## Signature Methods + + + + 1. Upload PDF and navigate to the signing location + 2. Click "Draw Signature" to open the signature pad + 3. Draw using mouse or touchscreen + 4. Position and resize the signature on the page + 5. Apply and download + + A touchscreen or stylus gives the best results. + + + 1. Upload PDF + 2. Click "Text Signature" + 3. Type your name and choose a cursive/script font + 4. Position and apply + + + 1. Upload PDF + 2. Click "Upload Signature" + 3. Select a PNG/JPG of your signature + 4. Position, resize, and apply + + Use a PNG with transparent background for best results. + + --- -## How to Sign PDFs - -### Method 1: Draw Your Signature - -1. **Upload PDF** - Select document to sign -2. **Navigate to Page** - Find where you need to sign -3. **Click "Draw Signature"** - Opens signature pad -4. **Draw** - Use mouse or touchscreen to draw signature -5. **Position** - Drag signature to correct location -6. **Resize** - Adjust signature size -7. **Apply** - Add signature to PDF -8. **Download** - Save signed document - -**Tips:** -- Use a touchscreen or stylus for best results -- Draw slowly for smoother lines -- Click "Clear" to redraw if needed -- Make signature large enough to be legible - -### Method 2: Type Your Signature - -1. **Upload PDF** -2. **Click "Text Signature"** -3. **Type Your Name** - Enter text for signature -4. **Choose Font** - Select cursive/script font -5. **Position and Size** - Adjust placement -6. **Apply** - Add to PDF - -**Best For:** Quick signing when handwriting isn't practical. +## Pre-stored Signatures -### Method 3: Upload Signature Image - -1. **Upload PDF** -2. **Click "Upload Signature"** -3. **Select Image** - Choose PNG/JPG of your signature -4. **Position and Resize** - Place on document -5. **Apply** - Add to PDF - -**Best For:** Consistent signature appearance across documents. - ---- - -## Using Pre-stored Signatures - -You can configure Stirling PDF to load pre-stored signature files for quick access. This is useful for: -- Consistent signature appearance -- Quick signing of multiple documents -- Team/organization signature standards +Configure Stirling PDF to load pre-stored signature files for quick, consistent signing across documents. **Configuration:** [Sign with Custom Files](../../Configuration/Sign%20with%20custom%20files) @@ -93,280 +55,29 @@ You can configure Stirling PDF to load pre-stored signature files for quick acce ## Signature Options -### Appearance - -**Transparency:** -- Make signature background transparent -- Blend naturally with document - -**Color:** -- Traditional blue ink -- Black ink -- Custom colors - -**Size:** -- Adjust to fit signature line -- Maintain aspect ratio -- Scale up/down as needed - -### Position - -**Placement:** -- Drag and drop to any location -- Align to signature lines -- Position relative to form fields - -**Rotation:** -- Rotate if needed -- Adjust angle - -**Pages:** -- Sign on single page -- Add to multiple pages -- Different signatures per page - ---- - -## Best Practices - -### Creating Good Signatures - -**For Drawn Signatures:** -1. Use a stylus or touchscreen if possible -2. Draw slightly larger than needed (easier to scale down) -3. Use consistent speed for smooth lines -4. Practice in signature pad before applying -5. Keep signature simple (complex signatures may not look good) - -**For Image Signatures:** -1. Scan or photograph on white paper -2. High contrast (dark ink, white background) -3. Crop tightly around signature -4. Save as PNG with transparent background -5. High resolution (300 DPI minimum) - -### Document Signing - -**Before Signing:** -1. Read the entire document -2. Verify all details are correct -3. Ensure you have authority to sign -4. Check signature placement locations - -**While Signing:** -1. Place signature within designated areas -2. Don't cover important text -3. Size appropriately for signature line -4. Add date if required -5. Add initials if multiple pages - -**After Signing:** -1. Save original unsigned copy (optional) -2. Download signed PDF -3. Verify signature appears correctly -4. Distribute or submit as needed +- **Transparency** - Make signature background transparent +- **Color** - Blue, black, or custom ink color +- **Size** - Adjust to fit signature line +- **Rotation** - Adjust angle if needed +- **Pages** - Sign on single page, multiple pages, or different signatures per page --- -## Signature Types Comparison - -### Visual vs. Digital Signatures +## Visual vs. Digital Signatures -| Feature | Visual Signature (This Tool) | Digital Signature ([Certificate](./Certificate-Signing)) | -|---------|------------------------------|-------------------------------------------------------------| -| **Appearance** | Handwritten/image | May include visual + certificate info | +| | Visual Signature (This Tool) | Digital Signature ([Certificate](./Certificate-Signing)) | +|---|---|---| | **Security** | Visual only, can be copied | Cryptographically secure | | **Authentication** | No verification | Proves signer identity | -| **Tamper Detection** | None | Detects any changes after signing | -| **Legal Validity** | Varies by jurisdiction | Legally binding in many countries | -| **Use Case** | Forms, casual documents | Contracts, legal documents | +| **Tamper Detection** | None | Detects changes after signing | | **Setup** | None required | Requires certificate | -### When to Use Each - -**Use Visual Signing (This Tool) When:** -- ✅ Signing forms and applications -- ✅ Internal documents -- ✅ Casual agreements -- ✅ Documents that just need a visual signature -- ✅ No cryptographic verification needed - -**Use Digital Signing ([Certificate](./Certificate-Signing)) When:** -- ✅ Legal contracts requiring authentication -- ✅ Compliance and regulatory documents -- ✅ Documents that must prove integrity -- ✅ Multi-party agreements needing verification -- ✅ Legally binding signatures required - ---- - -## Multiple Signatures - -### Signing as Multiple People - -**Option 1: Sequential Signing** -1. First person signs and saves -2. Second person opens signed PDF -3. Second person adds their signature -4. Continue for additional signers - -**Option 2: Signature Coordination** -1. Each person creates their signature image -2. One person uploads all signatures -3. Places each signature in correct location - -### Team Signatures - -For organizations needing standardized signatures: -1. Store signature images on server -2. Configure pre-loaded signatures -3. Users select from available signatures -4. Consistent appearance across documents - -**Setup:** [Sign with Custom Files](../../Configuration/Sign%20with%20custom%20files) - ---- - -## Common Issues - -### "Signature looks pixelated" - -**Causes:** -- Drew too small and scaled up -- Low resolution image -- Compressed too much - -**Solutions:** -- Draw signature larger -- Use higher resolution image (300+ DPI) -- Save as PNG, not JPG - -### "Signature doesn't match signature line" - -**Causes:** -- Signature too large or small -- Wrong aspect ratio -- Position slightly off - -**Solutions:** -- Resize to fit signature line -- Adjust aspect ratio if needed -- Zoom in for precise positioning - -### "Can't draw smooth signature" - -**Causes:** -- Using mouse (not ideal for drawing) -- Drawing too fast -- No stylus/touchscreen - -**Solutions:** -- Use touchscreen or stylus if available -- Draw more slowly -- Consider uploading signature image instead -- Use text signature as alternative - ---- - -## Security Considerations - -### What Visual Signatures DON'T Provide - -**⚠️ No Authentication:** -- Anyone can draw/add any signature -- No way to verify who actually signed -- Can be copied from other documents - -**⚠️ No Tamper Protection:** -- Document can be edited after signing -- No way to detect changes -- Signature can be moved/removed - -**⚠️ Limited Legal Standing:** -- May not be legally binding -- Jurisdiction-dependent -- Check local laws and requirements - -### When Visual Signatures Are Sufficient - -**✅ Appropriate For:** -- Internal company forms -- Consent forms (non-legal) -- Acknowledgment of receipt -- Casual agreements -- Personal documents - -**❌ NOT Appropriate For:** -- Legal contracts (use [digital signatures](./Certificate-Signing)) -- Financial documents requiring verification -- Government/regulatory submissions -- Documents requiring proof of identity -- Multi-party agreements needing authentication - ---- - -## Legal Considerations - -### Electronic Signature Laws - -Different jurisdictions have different requirements: - -**US (ESIGN Act):** -- Visual signatures generally accepted -- Intent to sign is key -- Record retention required - -**EU (eIDAS Regulation):** -- Three signature levels: Simple, Advanced, Qualified -- Visual signatures = Simple Electronic Signatures -- Limited legal weight compared to qualified signatures - -**Always:** -- Check local laws and requirements -- Consult legal counsel for important documents -- Use digital signatures for legally binding documents - ---- - -## API Usage - -Add signatures programmatically via API: - -```bash -# This tool is primarily interactive -# For programmatic signing, use certificate signing: -curl -X POST http://stirling-pdf:8080/api/v1/sign/cert \ - -F "fileInput=@document.pdf" \ - -F "certFile=@certificate.p12" \ - -F "password=certpass" \ - -o signed.pdf -``` - -See [API Documentation](../../API.md) for complete endpoint reference. +Visual signatures do **not** provide authentication, tamper protection, or guaranteed legal standing. For legally binding signatures requiring verification, use [Certificate Signing](./Certificate-Signing). --- ## Related Tools - **[Certificate Signing](./Certificate-Signing)** - Digital signatures with certificates -- **[Add Image](../Advanced-Tools#add-image)** - Add logos or other images - **[Add Stamp](../Content-Editing#stamps--annotations)** - Add official stamps -- **[Flatten](../Security#permissions--access-control)** - Make signatures non-editable - **[Add Password](../Security#password-protection)** - Protect signed documents - ---- - -## Summary - -Stirling PDF's Sign tool provides: - -✅ **Three signature methods** - Draw, type, or upload -✅ **Easy positioning** - Drag and drop placement -✅ **Customizable appearance** - Size, color, transparency -✅ **Multiple signatures** - Sign as multiple parties -✅ **Pre-stored signatures** - Quick access to saved signatures -✅ **No setup required** - Start signing immediately - -Perfect for forms, applications, and documents needing visual signatures! - -**Need authentication and legal validity?** Use [Certificate Signing](./Certificate-Signing) instead. diff --git a/docs/Functionality/The Technologies.md b/docs/Functionality/The Technologies.md index 232cc667..c3198044 100644 --- a/docs/Functionality/The Technologies.md +++ b/docs/Functionality/The Technologies.md @@ -1,107 +1,35 @@ --- -sidebar_position: 0 -description: What makes Stirling PDF powerful - technologies and capabilities! +sidebar_position: 99 +description: Open-source libraries and tools used by Stirling PDF --- -# What Makes Stirling PDF Powerful +# Third-Party Credits -Stirling PDF combines server-side processing power with modern browser capabilities to give you the best PDF experience possible. +Stirling PDF is built on these open-source projects. -## Key Features +## Server-Side -### Work Offline with Browser Storage -- **Your files stay in your browser** - No need to re-upload files when switching between tools -- **Faster workflows** - Skip the upload wait time when working with the same files -- **Preview thumbnails** - See what your files look like before processing -- **Privacy first** - Files are stored locally in your browser, not on our servers between operations - -### Undo and Redo Your Work -- **Made a mistake?** Go back to previous versions of your file -- **Try different options** - Experiment with settings and revert if needed -- **Work confidently** - Know you can always undo changes - -### File History Tracking -- **See what you've done** - Track all the operations you've performed -- **Jump back in time** - Restore earlier versions of your files -- **Clear when needed** - Remove local files and history whenever you want - -### Desktop Applications -- **Windows, Mac, and Linux** native applications available -- **Open PDFs directly** - Double-click PDF files to open them in Stirling PDF -- **No browser needed** - Standalone application with all features -- **Automatic updates** - Stay up to date with the latest features - -### Modern, Responsive Interface -- **Fast and smooth** - Modern web technology for a better experience -- **Works on any device** - Responsive design for desktop, tablet, and mobile -- **Real-time previews** - See changes as you make them -- **Dark mode** - Easy on your eyes - -### Flexible Deployment Options -- **All-in-one container** - Simple Docker deployment with everything included -- **Split frontend and backend** - Scale and deploy components separately -- **Serve frontend from CDN** - Ultra-fast page loads worldwide -- **Run anywhere** - Cloud, self-hosted, or on your desktop - -## The Technology Behind It - -### Processing Power (Server-Side) -Stirling PDF uses powerful open-source tools to handle complex PDF operations: - -- **[PDFBox](https://pdfbox.apache.org/)** - Core PDF manipulation for most operations -- **[LibreOffice](https://www.libreoffice.org/)** - Advanced file conversions (Office documents, images, etc.) +- **[PDFBox](https://pdfbox.apache.org/)** - Core PDF manipulation +- **[LibreOffice](https://www.libreoffice.org/)** - Office document conversions - **[qpdf](https://qpdf.sourceforge.io/)** - Specialized PDF operations -- **[Tesseract OCR](https://github.com/tesseract-ocr/tesseract)** - Extract text from images in PDFs -- **[OpenCV](https://opencv.org/)** - Image processing and computer vision operations - -### Modern Web Experience (Browser-Side) -A fast, modern interface built with powerful frontend technologies: +- **[Tesseract OCR](https://github.com/tesseract-ocr/tesseract)** - Text recognition from images +- **[OpenCV](https://opencv.org/)** - Image processing -**Core Framework:** -- **[React](https://react.dev/)** - Modern UI framework for responsive interfaces -- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe development -- **[Vite](https://vitejs.dev/)** - Lightning-fast build tool +## Frontend -**PDF Rendering & Interaction:** -- **[EmbedPDF](https://www.embedpdf.com/)** - Open-source PDF viewer with annotation support -- **[PDF.js](https://mozilla.github.io/pdf.js/)** - Mozilla's PDF rendering engine +- **[React](https://react.dev/)** + **[TypeScript](https://www.typescriptlang.org/)** with **[Vite](https://vitejs.dev/)** +- **[EmbedPDF](https://www.embedpdf.com/)** / **[PDF.js](https://mozilla.github.io/pdf.js/)** - PDF viewing and annotation - **[pdf-lib](https://pdf-lib.js.org/)** - Client-side PDF manipulation +- **[Mantine](https://mantine.dev/)** - UI components +- **[i18next](https://www.i18next.com/)** - 30+ language translations -**UI & Components:** -- **[Mantine](https://mantine.dev/)** - Modern React component library -- **[Material UI](https://mui.com/)** - Additional UI components -- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first styling -- **[Iconify](https://iconify.design/)** - Unified icon framework - -**Enhanced Features:** -- **[i18next](https://www.i18next.com/)** - Internationalization (30+ languages) -- **[signature_pad](https://github.com/szimek/signature_pad)** - Canvas-based signatures -- **[JSZip](https://stuk.github.io/jszip/)** - Client-side ZIP handling -- **[Axios](https://axios-http.com/)** - HTTP client for API communication - -### Desktop Applications -Native applications built with modern desktop technology: - -- **[Tauri](https://tauri.app/)** - Rust-based native app framework - - **Automatic PDF file association** - Open PDFs directly in Stirling PDF - - **Bundled processing tools** - Everything you need included - - **System integration** - Feels like a native application - - **One-click installers** - Easy installation on all platforms - - **Small footprint** - Efficient resource usage - -## Open Source and Transparent +## Desktop -All the technologies we use are open source and well-documented: +- **[Tauri](https://tauri.app/)** - Native app framework (Windows, Mac, Linux) -- View all Java application licenses on our [licenses page](https://stirlingpdf.io/licenses) -- Review our source code on [GitHub](https://github.com/Stirling-Tools/Stirling-PDF) -- No vendor lock-in - Deploy and customize as needed -- Community-driven development +## Browser File Storage -## Privacy and Security +Files are stored locally in your browser's [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) between operations. They never leave your device until you process them. Clear storage when done on shared computers. -Designed with privacy in mind: +## Source Code -- **Browser storage stays local** - Files cached in your browser never leave your device -- **Open source** - Audit the code yourself -- **No tracking required** - Disable analytics completely if desired -- **Your data, your control** - Self-host on your own infrastructure +- [GitHub](https://github.com/Stirling-Tools/Stirling-PDF) diff --git a/docs/Getting Started.md b/docs/Getting Started.md index 16773b70..ec775743 100644 --- a/docs/Getting Started.md +++ b/docs/Getting Started.md @@ -27,27 +27,26 @@ Stirling PDF is a locally hosted web application that allows you to perform vari V2 brings major improvements to performance, workflow, and deployment flexibility: -- **📁 Stateful Processing** - Upload once, use across multiple tools without re-uploading -- **⏮️ Undo & Redo** - Made a mistake? Just undo it! Full version history included -- **🖥️ Native Desktop Apps** - Lightning-fast startup, "Open with" integration, offline capable -- **🔀 Split Deployment** - Scale frontend and backend independently for enterprise use -- **⚙️ In-App Settings** - Configure everything through the UI, no file editing needed +- **Stateful Processing** - Upload once, use across multiple tools without re-uploading +- **Undo & Redo** - Full version history for page editing +- **Native Desktop Apps** - Fast startup, "Open with" integration, offline capable +- **In-App Settings** - Configure everything through the UI, no file editing needed --- ## Documentation Guide -### 👤 For Individual Users +### For Individual Users **[Tool Reference](./Functionality/Functionality.md)** -Browse all 60+ PDF tools with descriptions and use cases +Browse all 60+ PDF tools with descriptions --- -### 🏢 For Organizations & IT Teams +### For Organizations & IT Teams **[Production Deployment Guide](./Server-Admin-Onboarding.md)** -Complete walkthrough: installation → configuration → security → monitoring +Complete walkthrough: installation - configuration - security - monitoring **[Paid Offerings (Server & Enterprise)](./Paid-Offerings)** External databases, Google Drive integration, SSO, advanced monitoring, and priority support @@ -57,13 +56,13 @@ All configuration options for Docker and server deployments --- -### 🔧 For Developers & Integration +### For Developers & Integration **[API Documentation](./API.md)** Integrate Stirling PDF into your applications and workflows **[Configuration](./Configuration/System%20and%20Security.md)** -SSO, split deployment, certificates, security settings, and more +SSO, certificates, security settings, and more **[Contribute Guide](./Contribute.md)** Help improve Stirling PDF - development setup and guidelines @@ -74,7 +73,7 @@ Help improve Stirling PDF - development setup and guidelines Choose how you want to run Stirling PDF based on your needs: -### 🖥️ Desktop Applications +### Desktop Applications Native apps with system integration: @@ -85,11 +84,11 @@ Native apps with system integration: | **Mac (Intel)** | [DMG](https://files.stirlingpdf.com/mac-x86_64-installer.dmg) | [Mac Guide](./Installation/Mac.md) | | **Linux** | [DEB](https://files.stirlingpdf.com/linux-installer.deb) | [Unix Guide](./Installation/Unix.md) | -**Features:** Lightning-fast startup, "Open with" integration, sign in with Stirling Cloud or self-hosted server +**Features:** Fast startup, "Open with" integration, sign in with Stirling Cloud or self-hosted server --- -### 🐳 Docker Deployment +### Docker Deployment Recommended for server deployments and organizations: @@ -103,14 +102,14 @@ docker run -d \ **Available versions:** - `latest` - Standard version (recommended) -- `latest-fat` - Includes extra fonts and security features +- `latest-fat` - Extra fonts and tools for highest quality conversions and full format support - `latest-ultra-lite` - Minimal size for resource-constrained environments **Full guide:** [Docker Installation Guide](./Installation/Docker%20Install.md) --- -### ⚙️ Manual Server Setup +### Manual Server Setup For bare metal installations or environments without Docker: diff --git a/docs/Installation/Docker Install.md b/docs/Installation/Docker Install.md index 47473d62..e60b8086 100644 --- a/docs/Installation/Docker Install.md +++ b/docs/Installation/Docker Install.md @@ -52,90 +52,27 @@ Then open `http://localhost:8080` in your browser! ## Choosing Your Version -Stirling PDF offers three versions depending on your needs: - | Version | Tag | What's Included | Best For | |---------|-----|-----------------|----------| | **Standard** | `latest` | All PDF features | Most users, balanced features & size | -| **Fat** | `latest-fat` | Everything + extra tools | Maximum features, larger container | +| **Fat** | `latest-fat` | Everything + extra fonts & tools | Highest quality conversions, full format support | | **Ultra-Lite** | `latest-ultra-lite` | Core features only | Limited resources, minimal size | **Most users should use `latest`** - it has everything you need. ### When to use each version: -**Standard (`latest`)** - Use this if: -- ✅ You want all PDF features -- ✅ You have normal server/computer specs -- ✅ You're not sure which to pick +**Standard (`latest`)** - You want all PDF features, have normal server specs, or you're not sure which to pick. -**Fat (`latest-fat`)** - Use this if: -- 📦 You need every possible conversion format -- 📦 You want all optional tools included -- 📦 Disk space isn't a concern +**Fat (`latest-fat`)** - You need the highest quality conversions with full font support, every conversion format, and all optional tools. Disk space isn't a concern. -**Ultra-Lite (`latest-ultra-lite`)** - Use this if: -- 💾 Running on very limited hardware (Raspberry Pi, low-end VPS) -- 💾 Want fastest startup time -- 💾 Only need basic PDF operations +**Ultra-Lite (`latest-ultra-lite`)** - Running on very limited hardware (Raspberry Pi, low-end VPS), want fastest startup, or only need basic PDF operations. To use a different version, just change the tag: ```bash docker run -d stirlingtools/stirling-pdf:latest-ultra-lite ``` -## Deployment Options (V2.0+) - -V2.0 lets you run Stirling PDF in different ways depending on your needs: - -### Simple Deployment (Recommended) - -**MODE=BOTH (Default)** - Everything in one container - -- ✅ **Easiest setup** - One container does it all -- ✅ **Perfect for most users** - Single server hosting -- ✅ **No extra configuration** - Works out of the box - -```bash -docker run -d \ - --name stirling-pdf \ - -p 8080:8080 \ - -e MODE=BOTH \ - stirlingtools/stirling-pdf:latest -``` - -**Use this if:** You're running on a single server and want the simplest setup. - -### Advanced Deployment (Split Frontend/Backend) - -For advanced users who need to scale components independently: - -**MODE=BACKEND** - Backend API only -- Runs the PDF processing API server -- Multiple frontends can connect to one backend -- Scale processing power independently - -**MODE=FRONTEND** - Frontend only -- Serves the React web interface -- Can be deployed to CDN for global distribution -- Multiple instances for load balancing - -**Use split mode if:** -- Scaling frontend and backend independently -- CDN deployment for global frontend distribution -- Running multiple frontend instances with shared backend -- Microservices/containerized architecture - -### V2.0 Configuration Variables - -| Variable | What It Does | When You Need It | Example | -|----------|--------------|------------------|---------| -| `MODE` | Deployment type | Always (defaults to BOTH) | `MODE=BOTH` | -| `BACKEND_INTERNAL_PORT` | Internal backend port | Only for MODE=BOTH customization | `BACKEND_INTERNAL_PORT=8081` | -| `VITE_API_BASE_URL` | Where the backend is located | Required for MODE=FRONTEND | `VITE_API_BASE_URL=http://backend:8080` | - -**Most users don't need to set these** - the defaults work great! - ## Full Setup (With All Features) Want OCR, custom settings, and logging? Add more volumes: @@ -193,64 +130,11 @@ docker-compose up -d - `/logs` - Application logs - `/pipeline` - Automation configurations -**What this does:** -- Runs Stirling PDF on port 8080 -- Stores data in `./stirling-data` folder -- Automatically restarts if it crashes -- Everything in one container (MODE=BOTH is default) - -### Split Deployment (Advanced Users) - -Want to scale frontend and backend independently? Use this: - -Create `docker-compose.yml`: - -```yaml -services: - # Backend - PDF processing engine - stirling-backend: - image: stirlingtools/stirling-pdf:latest - container_name: stirling-backend - ports: - - '8081:8080' - volumes: - - ./stirling-data/tessdata:/usr/share/tessdata - - ./stirling-data/configs:/configs - - ./stirling-data/logs:/logs - - ./stirling-data/pipeline:/pipeline - environment: - - MODE=BACKEND # Backend only - restart: unless-stopped - - # Frontend - Web interface - stirling-frontend: - image: stirlingtools/stirling-pdf:latest - container_name: stirling-frontend - ports: - - '8080:8080' - environment: - - MODE=FRONTEND # Frontend only - - VITE_API_BASE_URL=http://stirling-backend:8080 # Where backend is located - depends_on: - - stirling-backend - restart: unless-stopped -``` - -**Benefits of split deployment:** -- Scale frontend and backend independently -- Run multiple frontends with one backend -- Deploy frontend globally via CDN -- Better resource allocation - -**When to use split:** -- High traffic websites -- Global user base -- Microservices architecture -- Need independent scaling - ## Updating Stirling PDF -### Docker Run + + + ```bash docker stop stirling-pdf docker rm stirling-pdf @@ -258,14 +142,19 @@ docker pull stirlingtools/stirling-pdf:latest # Then run your original docker run command ``` -### Docker Compose + + + ```bash docker-compose down docker-compose pull docker-compose up -d ``` -Your data is safe in the volumes and will persist across updates! + + + +Your data is safe in the volumes and will persist across updates. ## Common Configurations @@ -281,12 +170,6 @@ environment: - LANGS=es_ES # Spanish, or en_GB, fr_FR, de_DE, etc. ``` -### Multiple Languages -```yaml -environment: - - LANGS=en_GB,es_ES,fr_FR # Comma-separated -``` - ### Custom Port ```yaml ports: @@ -315,8 +198,3 @@ ports: - Check logs: `docker logs stirling-pdf` - Check system resources (RAM, disk space) - Try ultra-lite version for limited hardware - -**Features not working?** -- Some features need dependencies -- Check logs for missing requirements -- Consider using `latest-fat` for all features diff --git a/docs/Paid-Offerings.md b/docs/Paid-Offerings.md index 092ff632..84c4b945 100644 --- a/docs/Paid-Offerings.md +++ b/docs/Paid-Offerings.md @@ -40,6 +40,7 @@ Stirling PDF offers Server and Enterprise paid plans. These provide the same gre - Support tickets via support@stirlingpdf.com - [External Database](./Configuration/External%20Database.md) support for optimized deployments and load-balancing - Google Drive integration + - [OAuth2 SSO](./Configuration/OAuth%20SSO%20Configuration.md) (Google, GitHub, Keycloak, any OIDC provider) - **Perfect for**: Organizations with many users who want predictable, flat-rate pricing ### Enterprise Plan @@ -48,7 +49,7 @@ Stirling PDF offers Server and Enterprise paid plans. These provide the same gre - **Users**: Per-seat licensing (flexible scaling) - **Features**: - All Server Plan features, plus: - - [Advanced SSO](./Configuration/Single%20Sign-On%20Configuration.md), OAuth2 and SAML with automated login handling + - [SAML2 SSO](./Configuration/SAML%20SSO%20Configuration/SAML%20SSO%20Configuration.md) (Okta, Azure AD, etc.) with automated login handling - Custom automated metadata handling - Priority support tickets via support@stirlingpdf.com - 1:1 meetings with the Stirling PDF team (from registered email domain) @@ -63,9 +64,9 @@ Stirling PDF offers Server and Enterprise paid plans. These provide the same gre ## Purchasing a License -### V2.0 - In-App Purchase (Recommended) +### In-App Purchase (Recommended) -Stirling PDF V2.0 offers streamlined in-app purchasing and license activation: +Stirling PDF offers streamlined in-app purchasing and license activation: 1. **Navigate to Settings**: Log in as an admin and go to Settings → Admin Plan 2. **Select Your Plan**: Choose between Server (unlimited users) or Enterprise (per-seat) plans @@ -92,11 +93,11 @@ If you prefer to purchase outside the app or have questions: ## Activating Your License -### V2.0 - Automatic Activation +### Automatic Activation If you purchased in-app, your license is automatically activated. No further action needed! -### V2.0 - Manual Activation +### Manual Activation If you purchased via the website and received a license key by email: @@ -105,7 +106,7 @@ If you purchased via the website and received a license key by email: 3. **Activate**: Click "Activate License" 4. **Confirmation**: Your plan features will be enabled immediately -**No restart required** - license activation is dynamic in V2.0! +**No restart required** - license activation is dynamic! ### Legacy - settings.yml Activation @@ -142,7 +143,7 @@ For 100% offline air-gapped environments (Enterprise only), you can request a ce ### Billing Portal -V2.0 includes a convenient billing management interface: +Stirling PDF includes a convenient billing management interface: 1. Navigate to Settings → Admin Plan 2. Click "Manage Billing" @@ -237,7 +238,7 @@ A: Invoices are automatically sent via email and accessible through the Billing If you're upgrading from Stirling PDF V1 with an existing license: -1. Your existing license key will continue to work in V2 +1. Your existing license key will continue to work 2. You can enter it manually via Settings → Admin Plan 3. Or, re-activate through the in-app purchase flow 4. Contact support@stirlingpdf.com if you encounter any issues diff --git a/docs/Server-Admin-Onboarding.md b/docs/Server-Admin-Onboarding.md index fdab9602..4b91f344 100644 --- a/docs/Server-Admin-Onboarding.md +++ b/docs/Server-Admin-Onboarding.md @@ -521,8 +521,8 @@ MAIL_TLS_ENABLED=true **Best for:** Large enterprises, existing SSO infrastructure **Single Sign-On (SSO) options:** -- **OAuth2:** Enterprise only - Supports Google, GitHub, Keycloak, any OpenID Connect provider -- **SAML2:** Enterprise only - Supports Okta, Azure AD, etc. +- **OAuth2:** Server tier - Supports Google, GitHub, Keycloak, any OpenID Connect provider +- **SAML2:** Enterprise tier - Supports Okta, Azure AD, etc. **Key settings:** ```yaml @@ -1490,7 +1490,8 @@ Stirling-PDF offers **Server and Enterprise paid plans** with additional feature ### Key Paid Plan Features **Authentication & Security:** -- **SAML2 SSO:** Enterprise-grade single sign-on (OAuth2 is free) +- **OAuth2 SSO:** Server tier (Google, GitHub, Keycloak, OIDC) +- **SAML2 SSO:** Enterprise tier (Okta, Azure AD, etc.) - Enhanced security features **Database & Infrastructure:**