DocOps Block Processor Documentation

1. Overview

The DocOpsBlockProcessor is a powerful AsciidoctorJ extension that enables dynamic content generation through server-side processing. It creates interactive SVG visualizations and panels in AsciiDoc documents by connecting to a DocOps server.

2. Core Capabilities

2.1. Dynamic Content Generation

Server Integration: Connects to DocOps server (default: http://localhost:8010/extension)
Content Processing: Processes block content through external services
Multiple Output Formats: Supports SVG and PDF generation
Compression: Automatically compresses payload data using GZIP

2.2. Interactive Features

Zoom Controls: In/out zoom with reset functionality
Copy Functionality: Copy as SVG text or convert to PNG
Fullscreen Mode: Expand visualizations to full viewport
Theme Support: Light and dark theme compatibility

3. Basic Usage

The processor uses the docops block name with a required kind parameter:

[docops,kind="buttons"]

Your content here

4. Configuration Parameters

4.1. Required Parameters

Parameter Description

Parameter	Description
`kind`	Type of visualization to generate (e.g., "buttons", "flowchart", "dashboard")

kind

Type of visualization to generate (e.g., "buttons", "flowchart", "dashboard")

4.2. Optional Parameters

Parameter Type Default Description

Parameter	Type	Default	Description
`title`	String	"SVG Viewer"	Title for the generated content
`controls`	Boolean	false	Show interactive controls overlay
`copy`	Boolean	true	Allow copying functionality
`zoom`	Boolean	true	Enable zoom controls
`expand`	Boolean	true	Enable fullscreen mode
`theme`	String	"light"	Theme for controls (light/dark)
`role`	String	"center"	Alignment (left/center/right)
`useDark`	Boolean	false	Use dark theme for content
`scale`	String	"1.0"	Scaling factor for output

title

String

"SVG Viewer"

Title for the generated content

controls

Boolean

false

Show interactive controls overlay

copy

Boolean

true

Allow copying functionality

zoom

Boolean

true

Enable zoom controls

expand

Boolean

true

Enable fullscreen mode

theme

String

"light"

Theme for controls (light/dark)

role

String

"center"

Alignment (left/center/right)

useDark

Boolean

false

Use dark theme for content

scale

String

"1.0"

Scaling factor for output

5. Interactive Controls

When controls=true is enabled, the processor generates an interactive SVG viewer:

5.1. Zoom Controls

Zoom In (🔍+): Magnify content up to 5x
Zoom Out (🔍-): Reduce content down to 0.2x
Reset Zoom (⚪): Return to original size

5.2. Copy Options

Copy as SVG (📋 SVG): Copy SVG markup to clipboard
Copy as PNG (📋 PNG): Convert SVG to PNG and copy as image

5.3. Display Controls

Toggle Fullscreen (⛶): Expand to full viewport
Floating Controls: Minimalist gear icon (⚙️) overlay

6. Text Substitution

The processor supports dynamic text replacement using the pattern #[variable]:

:company-name: ACME Corp

[docops,kind="buttons"]

Welcome to #[company-name]

7. Environment Detection

7.1. IntelliJ IDEA Integration

When running in IntelliJ IDEA (env=idea): - Provides direct image embedding for IDE preview - Optimized for development workflow - Bypasses web-based rendering

7.2. PDF Generation

When backend=pdf: - Automatically detects PDF output - Generates appropriate image links - Handles scaling and formatting for print

8. Server Configuration

8.1. Document Attributes

Attribute Description

Attribute	Description
`panel-server`	Override default server URL for API calls
`panel-webserver`	Override web server URL for image generation
`local-debug`	Enable debug logging (true/false)

panel-server

Override default server URL for API calls

panel-webserver

Override web server URL for image generation

local-debug

Enable debug logging (true/false)

8.2. Server Health Checking

Automatic server availability verification via /api/ping
Graceful degradation when server unavailable
Configurable timeouts (20s connection, 1min request)

9. Alignment and Styling

9.1. Role-based Alignment

[docops,kind="buttons",role="left"]

Left-aligned content

[docops,kind="buttons",role="center"]

Centered content

[docops,kind="buttons",role="right"]

Right-aligned content

9.2. Responsive Design

Automatic width adjustment
Mobile-friendly controls
Scalable vector graphics

10. Error Handling

The processor includes comprehensive error handling:

Missing Parameters: Clear error messages for required parameters
Server Unavailable: Graceful fallback with user notification ("DocOps Server Unavailable! 😵")
Network Timeouts: Configurable timeout handling
Compression Errors: Safe error recovery with logging

11. Performance Features

11.1. Optimization

Content Compression: GZIP compression for payload efficiency
HTTP/2 Support: Modern HTTP client implementation
Server-side Caching: Caching through URL parameters
Lazy Loading: On-demand content generation

11.2. Resource Management

Connection pooling for HTTP requests
Automatic resource cleanup
Memory-efficient processing

12. Example Usage Scenarios

12.1. Basic Visualization

[docops,kind="flowchart"]

Start → Process → End

12.2. Interactive Dashboard

[docops,kind="dashboard",controls=true,theme="dark"]

metric1: 95% metric2: 87% metric3: 92%

12.3. PDF-Optimized Content

[docops,kind="diagram",scale="1.5"]

Component A -→ Component B Component B -→ Component C

12.4. Advanced Configuration

[docops,kind="buttons",controls=true,copy=true,zoom=true,expand=true,theme="dark",role="center",title="My Dashboard"]

{ "buttons": [ { "label": "Dashboard", "link": "/dashboard", "description": "Main dashboard view" } ] }

13. Integration Requirements

13.1. Prerequisites

DocOps Server: Running DocOps server instance
Network Access: Server accessible from AsciiDoc processing environment
AsciidoctorJ: Compatible with AsciidoctorJ extension framework

13.2. Installation

The processor is automatically registered through the PanelsRegistry extension:

registry.block(DocOpsBlockProcessor::class.java)

14. API Integration

14.1. Server Endpoints

GET /api/ping: Health check endpoint
GET /api/docops/svg: SVG generation endpoint with parameters:
kind: Visualization type
payload: Compressed content
type: Output format (SVG/PDF)
useDark: Dark theme flag
title: Content title
backend: Document backend
filename: Output filename
scale: Scaling factor (for PDF output)

14.2. URL Parameters

The processor constructs URLs with compressed payloads and configuration parameters, enabling server-side processing and caching.

15. Troubleshooting

15.1. Common Issues

Issue Cause Solution

Issue	Cause	Solution
"Parameter Error: Missing 'kind'"	Required `kind` parameter not provided	Add `kind` parameter: `[docops,kind="buttons"]`
"DocOps Server Unavailable! 😵"	Server not running or unreachable	Start DocOps server and verify network connectivity
Empty output	Invalid content or server error	Check server logs and enable `local-debug=true`
Controls not showing	`controls=false` or JavaScript disabled	Set `controls=true` and ensure JavaScript is enabled

"Parameter Error: Missing 'kind'"

Required kind parameter not provided

Add kind parameter: [docops,kind="buttons"]

"DocOps Server Unavailable! 😵"

Server not running or unreachable

Start DocOps server and verify network connectivity

Empty output

Invalid content or server error

Check server logs and enable local-debug=true

Controls not showing

controls=false or JavaScript disabled

Set controls=true and ensure JavaScript is enabled

15.2. Debug Mode

Enable debug logging by setting the document attribute:

:local-debug: true

This enables detailed logging of: - Server connectivity checks - URL construction - Content processing - Error details

16. Best Practices

16.1. Performance

Use appropriate scale values to balance quality and file size
Enable server-side caching for repeated content
Consider PDF-specific optimizations for print output

16.2. Accessibility

Provide meaningful title attributes
Use sufficient color contrast in custom themes
Ensure keyboard navigation works with interactive controls

16.3. Security

Validate server URLs in production environments
Use HTTPS for server communication when possible
Sanitize user input in content blocks

This comprehensive documentation covers all aspects of the DocOpsBlockProcessor capabilities, from basic usage to advanced configuration and troubleshooting.