A powerful cross-platform PDF bookmark generator using Ghostscript
Generate professional PDF bookmarks with advanced features like dynamic offsets, negative page support, and intelligent error detection
🚀 Features • 📦 Installation • 🔧 Usage • 📖 Examples • 🛠️ Development
- Cross-platform support - Windows, macOS, and Linux
- Smart TOC parsing - Multiple format support with automatic detection
- Dynamic page offsets - HTML comment-style offset commands
- Negative page support - Full support for negative page numbers
- Ghostscript integration - Professional PDF processing backend
- Bookmark preview - Preview and validate bookmarks before generation
- Intelligent error detection - Automatic problem identification and suggestions
- Multiple format support - Standard, dot-line, and custom formats
- Real-time validation - Check for issues before PDF generation
- Debug mode - Detailed logging and error diagnostics
- Clear original bookmarks - Remove existing bookmarks from PDFs using qpdf
- Comprehensive tool testing - Test both Ghostscript and qpdf functionality
- Enhanced UI - Modern interface with placeholder effects and keyboard shortcuts
- Beautiful interface - Modern design with intuitive layout
- Responsive design - Adapts to different screen sizes
- Visual feedback - Color-coded status indicators and progress updates
- Accessibility - Clear labels and helpful tooltips
- Python 3.7+ (with tkinter)
- Ghostscript (for PDF processing)
# Clone the repository
git clone https://github.com/vanabel/pdf-bookmarker.git
cd pdf-bookmarker
# Create virtual environment
python -m venv venv
source venv/bin/activate # macOS/Linux
# or
venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt# Start the GUI application
python pdf_bookmarker_gs.py
# Or use the provided scripts
./run_app.sh # macOS/Linux
run_app.bat # Windows- Select PDF - Choose the input PDF file
- Set Offset - Configure page offset (bookmark page 1 → PDF page X)
- Input TOC - Enter your table of contents
- Preview - Review bookmarks and check for issues
- Generate - Create the final PDF with bookmarks
PREFACE V
Chapter I. INTRODUCTION 1
1. Outline of this book 1
2. Further remarks 4
Preface ............................................. 7
Chapter I. INTRODUCTION ............................ 1
1. Outline of this book .......................... 1
<!---offset -13--->
PREFACE 5
PREFACE TO REVISED EDITION 7
<!---offset +13 --->
Chapter I. INTRODUCTION
1. Outline of this book 1
- Click "👁️ Preview Bookmarks" to review before generation
- Automatic error detection and warnings
- Visual validation of page numbers and offsets
- Click "🧪 Test Ghostscript" to verify installation
- Comprehensive diagnostics and troubleshooting
- Version and capability verification
- Enable detailed console output
- Step-by-step process logging
- Error trace and diagnostic information
- Remove existing bookmarks from PDFs
- Useful for cleaning up before adding new bookmarks
- Preserves PDF content while removing bookmark metadata
- Comprehensive testing of Ghostscript and qpdf
- Detailed diagnostics and installation guidance
- One-click verification of all dependencies
# macOS
chmod +x build_macos.sh
./build_macos.sh
# Windows
build_windows.bat
# Universal
python build_app.pyAfter building, you'll get:
- Executable file -
dist/PDF书签生成器 - Launch scripts - Platform-specific startup scripts
- User manual - Complete usage instructions
Users can run the application without installing Python!
This application requires two external tools for full functionality:
- Ghostscript - For PDF bookmark generation
- qpdf - For clearing original PDF bookmarks
📖 Detailed installation guide is available in the docs/ directory:
macOS:
brew install ghostscript qpdfWindows:
- Download from Ghostscript and qpdf
- Install and add to system PATH
Linux (Ubuntu/Debian):
sudo apt-get update
sudo apt-get install ghostscript qpdf# Optional: Custom tool paths
export GS_PATH="/usr/local/bin/gs"
export QPDF_PATH="/usr/local/bin/qpdf"pdf-bookmarker/
├── 📱 pdf_bookmarker_gs.py # Main application
├── 🔍 bookmark_validator.py # Standalone validation tool
├── 🐛 debug_ghostscript.py # Ghostscript diagnostics
├── 🎯 demo.py # Feature demonstration
├── 📦 build_app.py # Application packaging
├── 🚀 build_macos.sh # macOS build script
├── 🪟 build_windows.bat # Windows build script
├── 📚 demo/ # Example files and samples
│ ├── 📖 full_bookmarks.txt # Complete academic book TOC
│ ├── 🔢 simple_bookmarks.txt # Basic chapter structure
│ ├── 📊 dots_format_bookmarks.txt # Dot-line format
│ ├── ⚙️ dynamic_offset_bookmarks.txt # Dynamic offset examples
│ └── 📄 *.pdf # Sample PDF files
├── 📋 requirements.txt # Python dependencies
├── 📖 README.md # This file
├── 🚫 .gitignore # Git ignore rules
└── 📄 LICENSE # MIT License
The demo/ directory contains comprehensive examples:
cd demo
python load_examples.py # List all examples
python load_examples.py simple_bookmarks.txt # View basic example
python load_examples.py full_bookmarks.txt --copy # Copy to clipboard<!---offset -13--->
PREFACE 5
PREFACE TO REVISED EDITION 7
<!---offset +13 --->
Chapter I. INTRODUCTION
1. Outline of this book 1
2. Further remarks 4
3. Notation 5
# Clone and setup
git clone https://github.com/vanabel/pdf-bookmarker.git
cd pdf-bookmarker
python -m venv venv
source venv/bin/activate
# Install development dependencies
pip install -r requirements.txt
pip install pytest black flake8 # Optional: testing and linting- Python: PEP 8 compliant
- GUI: Tkinter with ttk widgets
- Architecture: Object-oriented with clear separation of concerns
# Run tests
python -m pytest
# Run specific test
python test_app.py# Check installation
gs --version
# Verify PATH
which gs # macOS/Linux
where gs # Windows- Ensure Python 3.7+ is installed
- Check tkinter availability:
python -c "import tkinter" - Verify virtual environment activation
- Check Ghostscript installation
- Verify input PDF is not corrupted
- Review error logs in the application
Enable debug mode to get detailed information:
- Check "🐛 Debug Mode" in the application
- View console output for detailed logs
- Use "🧪 Test Ghostscript" for diagnostics
We welcome contributions! Here's how you can help:
- 🐛 Report bugs - Use GitHub Issues
- 💡 Suggest features - Open feature requests
- 📝 Improve documentation - Submit PRs for docs
- 🔧 Fix issues - Submit pull requests
- 🌍 Add translations - Help with internationalization
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Add tests if applicable
- Commit:
git commit -m 'Add amazing feature' - Push:
git push origin feature/amazing-feature - Open a Pull Request
- Follow PEP 8 style guidelines
- Add docstrings for new functions
- Include type hints where appropriate
- Write clear commit messages
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License Benefits:
- ✅ Free for commercial use
- ✅ Modify and distribute
- ✅ Use in proprietary software
- ✅ Minimal restrictions
- Ghostscript Team - For the powerful PDF processing engine
- Python Community - For the excellent tkinter GUI framework
- Open Source Contributors - For inspiration and feedback
For detailed guides, troubleshooting, and advanced usage, visit our comprehensive documentation:
- 📚 Documentation Center - Complete documentation index
- 🚀 New Features Guide - Latest features and improvements
- 🔧 Installation Guides - Step-by-step setup instructions
- 📋 Feature Documentation - Detailed usage and configuration
- Debug Mode: Debug Mode Explanation
- Clear Bookmarks: Clear Bookmarks Feature
- Tool Testing: Use "🧪 Test Tools" button in the application
- 📖 Documentation - This README and detailed docs
- 🐛 Issues - GitHub Issues
- 💬 Discussions - GitHub Discussions
- 📧 Email - Open an issue for direct contact
- ⭐ Star the repo - Show your support
- 👀 Watch - Get notified of updates
- 🔔 Notifications - Stay informed about releases
Made with ❤️ by the PDF Bookmarker Team
