Skip to content

README.md

Latest commit

 

History

History
138 lines (100 loc) · 4.56 KB

README.md

File metadata and controls

138 lines (100 loc) · 4.56 KB
Raw

Paperless-ngx Saver - Chrome Extension

A Chrome extension that allows you to save webpages as PDFs or upload existing PDFs directly to your Paperless-ngx instance.

Features

  • Save any webpage as PDF - Convert the current webpage to PDF and upload to Paperless-ngx
  • Upload existing PDFs - When viewing a PDF, upload it directly to Paperless-ngx
  • Add metadata - Include custom titles and tags when saving documents
  • Simple configuration - Easy setup with your Paperless-ngx URL and API token

Installation

Step 1: Generate Icons

  1. Open create-icons.html in your browser
  2. Click each download button to generate the required icons:
    • icon16.png
    • icon48.png
    • icon128.png
  3. Save all three icons to the icons/ folder in this extension directory

Step 2: Load Extension in Chrome

  1. Open Chrome and navigate to chrome://extensions/
  2. Enable "Developer mode" using the toggle in the top right
  3. Click "Load unpacked"
  4. Select the ChromePaperless folder
  5. The extension should now appear in your extensions list

Step 3: Configure Paperless-ngx Settings

  1. Click the extension icon in your Chrome toolbar
  2. Click "Configure Paperless-ngx Settings"
  3. Enter your Paperless-ngx URL (e.g., https://paperless.example.com)
  4. Generate an API token in Paperless-ngx:
    • Go to your Paperless-ngx instance
    • Navigate to Settings → API Tokens
    • Create a new token
  5. Paste the token into the extension settings
  6. Click "Test Connection" to verify everything works
  7. Click "Save Settings"

Usage

Saving a Webpage

  1. Navigate to any webpage you want to save
  2. Click the extension icon
  3. (Optional) Add a custom title or tags
  4. Click "Save to Paperless"
  5. The page will be converted to PDF and uploaded to your Paperless-ngx instance

Uploading a PDF

  1. Open a PDF in Chrome (either from a URL or a local file)
  2. Click the extension icon
  3. (Optional) Add a custom title or tags
  4. Click "Save to Paperless"
  5. The PDF will be uploaded directly to your Paperless-ngx instance

How It Works

  • Webpage to PDF: Uses Chrome's built-in printToPDF API to convert webpages
  • PDF Upload: Downloads the PDF and uploads it to Paperless-ngx
  • API Integration: Uses the Paperless-ngx REST API (/api/documents/post_document/)
  • Metadata: Supports document titles and tags

Permissions Explained

The extension requires the following permissions:

  • activeTab - To access the current tab's content and convert it to PDF
  • storage - To save your Paperless-ngx settings
  • notifications - To show success/error notifications
  • host_permissions - To download PDFs and communicate with your Paperless-ngx instance

Troubleshooting

"Settings not configured" error

Make sure you've entered both your Paperless-ngx URL and API token in the settings page.

"Connection failed" error

  • Verify your Paperless-ngx URL is correct and accessible
  • Check that your API token is valid
  • If using HTTPS for Paperless, ensure the certificate is valid
  • Check that your Paperless-ngx instance is reachable from your browser

PDF conversion issues

Some complex webpages may not convert perfectly to PDF. This is a limitation of Chrome's built-in PDF conversion.

CORS errors

If you encounter CORS errors, you may need to configure your Paperless-ngx instance to allow requests from the Chrome extension.

Development

File Structure

ChromePaperless/
├── manifest.json          # Extension manifest
├── popup.html            # Extension popup UI
├── popup.js              # Popup logic
├── options.html          # Settings page UI
├── options.js            # Settings page logic
├── background.js         # Background service worker (PDF conversion & upload)
├── create-icons.html     # Icon generator utility
├── icons/                # Extension icons
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
└── README.md            # This file

API Endpoints Used

  • GET /api/ - Test connection
  • POST /api/documents/post_document/ - Upload document with metadata

Privacy

This extension:

  • Only communicates with YOUR Paperless-ngx instance
  • Stores settings locally in Chrome's sync storage
  • Does not send data to any third parties
  • Runs entirely locally except for uploads to your configured Paperless instance

License

MIT

Contributing

Feel free to submit issues and enhancement requests!

Acknowledgments

Built for use with Paperless-ngx, an excellent document management system.