@confytome/confluence

Confluence-ready Markdown generator for confytome. Generates Pandoc-style Markdown from OpenAPI specifications and copies it to your clipboard for direct paste into Confluence pages.

✨ Features

• 📋 Clipboard Integration - Generated markdown copied to clipboard automatically
• 📝 Pandoc-style Markdown - Clean formatting compatible with Confluence editor
• 🔧 Automatic OpenAPI Integration - Generate spec from JSDoc or use existing
• 🌍 Unicode Support - Full Turkish and international character support
• 🔗 Anchor Link Control - Optional URL encoding for anchor links
• ⚡ Standalone Operation - Works with existing OpenAPI specs
• 🕐 Timestamped Documentation - Generation metadata included

📦 Installation

# Global installation
npm install -g @confytome/confluence

# Or use with npx (no installation)
npx @confytome/confluence generate --help

🚀 Usage

Standalone Usage (Recommended)

# Use existing OpenAPI spec - No additional dependencies required
npx @confytome/confluence generate --spec ./confytome/api-spec.json --output ./confytome

With confytome.json Configuration

# Generate spec from JSDoc and produce docs in one step - Requires @confytome/core
npx @confytome/confluence generate --config ./confytome.json --output ./confytome

⚙️ Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --spec | -s | Path to OpenAPI spec file | ./confytome/api-spec.json | | --output | -o | Output directory for generated files | ./confytome | | --version | -V | Show version number | | | --help | -h | Show help information | | | --config | -c | Server config JSON file (for generating spec from JSDoc) | | | --files | -f | JSDoc files to process | | | --no-brand | | Exclude confytome branding from documentation | | | --no-url-encode | | Disable URL encoding for anchor links | | | --no-clipboard | | Skip copying markdown to clipboard | |

🎯 Usage Scenarios

✅ Scenario 1: Standalone with Existing Spec

Perfect when you already have an OpenAPI specification file.

npx @confytome/confluence generate --spec ./confytome/api-spec.json

• ✅ No additional dependencies
• ✅ Works immediately
• ✅ Perfect for CI/CD pipelines

⚙️ Scenario 2: Generate from Code

When you want to generate the OpenAPI spec from your API code first.

npx @confytome/confluence generate --config ./confytome.json

• ⚠️ Requires @confytome/core for spec generation
• ✅ Full workflow from code to documentation
• ✅ Automatic spec generation

📁 Generated Output

Creates api-docs.md in the specified output directory and copies the content to your clipboard:

• API overview and server information
• All endpoints with request/response examples
• Data models and schemas
• Ready to paste directly into a Confluence page

Generated File Structure

confytome/
├── api-docs.md

Content Features

• Quick Reference - Table of contents with anchor links
• Server Information - Base URLs and environment details
• Endpoint Documentation - Complete request/response details
• Schema Definitions - Data model documentation
• Clipboard-ready - Paste directly into Confluence

🔧 Dependencies

• commander: CLI argument parsing
• clipboardy: Cross-platform clipboard access

💡 Examples

Basic Usage

# Simple generation with existing spec
npx @confytome/confluence generate --spec ./confytome/api-spec.json

CI/CD Integration

#!/bin/bash
# Generate Confluence Markdown documentation in CI
npx @confytome/confluence generate \
   --spec ./confytome/api-spec.json \
   --output ./confytome

Multiple Environments

# Production docs
npx @confytome/confluence generate \
   --spec ./specs/prod-api.json \
   --output ./docs/prod

# Staging docs
npx @confytome/confluence generate \
   --spec ./specs/staging-api.json \
   --output ./docs/staging

"Specified OpenAPI spec file not found"

# Check file path exists
ls -la ./confytome/api-spec.json

# Use absolute path if needed
npx @confytome/confluence generate --spec $(pwd)/confytome/api-spec.json

"No OpenAPI spec found, generating from JSDoc files..."

This is normal when using --config — the spec is generated automatically from your JSDoc annotations before docs are produced.

# Option 1: Use config to generate everything in one step
npx @confytome/confluence generate --config ./confytome.json

# Option 2: Use an existing spec directly
npx @confytome/confluence generate --spec ./confytome/api-spec.json

🌟 Part of confytome Ecosystem

@confytome/confluence is part of the confytome documentation ecosystem:

• @confytome/core - Plugin system & OpenAPI generator
• @confytome/markdown - Confluence-friendly Markdown docs
• @confytome/confluence - Confluence-ready Markdown with clipboard
• @confytome/html - Professional HTML docs
• @confytome/swagger - Interactive Swagger UI
• @confytome/postman - Postman collections

📄 License

MIT License - see the LICENSE file for details.

Generate beautiful Confluence Markdown documentation from OpenAPI specifications in seconds.