@codenteam/pandoc-server
v1.0.0
Published
A lightweight REST API server for Pandoc document conversion
Maintainers
fadysghatasReadme
Pandoc Server
A lightweight REST API server for Pandoc document conversion.
🚀 Features
- Multiple Output Formats: Text, blob (for downloads), and base64 encoding
- File Upload Support: Convert uploaded files or direct content input
- Binary & Text Handling: Automatic detection and appropriate formatting
- Security: Input validation, sanitization, and security headers
- Error Handling: Comprehensive error handling with detailed messages
- Docker Support: Ready-to-deploy Docker configuration
- Health Monitoring: Built-in health check and monitoring endpoints
Installation
Via npm (recommended)
npx @codenteam/pandoc-serverVia Docker
docker-compose upManual Installation
git clone https://github.com/codenteam/pandoc-server.git
cd pandoc-server
pnpm install # or npm
pnpm start # or npmUsage
Start the server:
npx @codenteam/pandoc-server --port=3000Convert documents via HTTP POST:
curl -X POST http://localhost:3000/convert \
-F "[email protected]" \
-F "to=pdf"API Endpoints
POST /convert- Convert documentsGET /formats- Get supported formatsGET /health- Health check
POST /converter/convert
Convert documents using Pandoc with custom arguments.
Request Body (JSON):
{
"args": ["--from", "markdown", "--to", "html"],
"input": "# Hello World\nThis is markdown content",
"outputFormat": "text",
"filename": "output.html"
}Request Body (Form Data for File Upload):
curl -X POST http://localhost:3000/converter/convert \
-F "[email protected]" \
-F 'args=["--from", "markdown", "--to", "pdf"]' \
-F 'outputFormat=blob' \
-F 'filename=document.pdf'Parameters:
args(Array): Pandoc command line argumentsinput(String): Direct content input (if no file)outputFormat(String):text,blob, orbase64filename(String): Output filename
Response Formats:
Text Format (JSON):
{
"content": "<html><body><h1>Hello World</h1></body></html>",
"filename": "output.html",
"mimeType": "text/html",
"format": "text",
"size": 45
}Base64 Format (JSON):
{
"content": "PGh0bWw+PGJvZHk+PGgxPkhlbGxvIFdvcmxkPC9oMT4=",
"filename": "output.html",
"mimeType": "text/html",
"format": "base64",
"size": 45
}Blob Format: Returns raw binary/text data with appropriate Content-Type headers for direct download.
GET /converter/formats
List all supported Pandoc input and output formats.
Response:
{
"input": ["markdown", "html", "docx", "..."],
"output": ["html", "pdf", "docx", "..."]
}GET /converter/version
Get the installed Pandoc version.
Response:
{
"version": "pandoc 3.5"
}GET /health
Health check endpoint.
Response:
{
"status": "ok",
"timestamp": "2024-01-01T12:00:00.000Z",
"service": "pandoc-server"
}🧪 Testing
Quick Test
# Start the server
pnpm start # or npm
# Run curl tests
./test.sh
# Or run Node.js tests
node test.jsExample Conversions
Markdown to HTML:
curl -X POST http://localhost:3000/converter/convert \
-H "Content-Type: application/json" \
-d '{
"args": ["--from", "markdown", "--to", "html"],
"input": "# Hello\n\nThis is **bold** text.",
"outputFormat": "text"
}'Markdown to PDF (download):
curl -X POST http://localhost:3000/converter/convert \
-H "Content-Type: application/json" \
-d '{
"args": ["--from", "markdown", "--to", "pdf"],
"input": "# My Document\n\nContent here.",
"outputFormat": "blob",
"filename": "document.pdf"
}' \
--output document.pdf⚙️ Configuration
Environment Variables
PORT- Server port (default: 3000)NODE_ENV- Environment mode
Supported Formats
The server supports all Pandoc input and output formats including:
Common Input Formats:
markdown,html,docx,odt,rtf,epub,latex,rst
Common Output Formats:
html,pdf,docx,odt,epub,latex,rtf,plain
🔒 Security
- Input validation and sanitization
- File size limits
- Dangerous argument detection
- Security headers (Helmet.js)
- CORS configuration
- Rate limiting (in production with nginx)
Extra Security
ExpressJS rate limiting
If you don't use nginx, you can do expressjs rate limiting using:
// Add to package.json dependencies
"express-rate-limit": "^7.1.5"
// Add to server.js
import rateLimit from 'express-rate-limit';
app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));Extra security headers
If you don't use a security layer (Firewall, LB, etc), you can add extra security headers using:
// Add to server.js
import helmet from 'helmet';
app.use(helmet({
contentSecurityPolicy: false, // Configure based on needs
crossOriginResourcePolicy: { policy: "cross-origin" }
}));🚢 Production Deployment
With Docker Compose
# Production deployment with nginx proxy
docker-compose --profile production up -dEnvironment Setup
- Install Pandoc on your system
- Set appropriate environment variables
- Configure reverse proxy (nginx/Apache)
- Set up monitoring and logging
- Configure backup for temporary files cleanup
📋 Requirements
- Node.js >= 16
- Pandoc >= 2.0 (installed on system)
- Optional: Docker for containerized deployment
🤝 Contributing
- Fork the repository
- Create a feature branch
- Submit a pull request
License
GPL-2.0 (same as Pandoc)