DocOps Extension Tutorial

1. Introduction

The DocOps Extension Server provides a powerful way to enhance your AsciiDoctor documents with interactive visualizations, charts, diagrams, and other dynamic elements. This tutorial will guide you through the process of setting up and using the DocOps extension to create beautiful, informative documentation.

Whether you’re documenting architecture decisions, creating project timelines, visualizing data with charts, or designing interactive navigation elements, the DocOps extension offers a comprehensive set of tools to elevate your technical documentation.

2. Getting Started

2.1. Prerequisites

Before you begin using the DocOps extension, ensure you have:

  • Java 11 or higher installed

  • Maven or Gradle for dependency management

  • Basic familiarity with AsciiDoctor

2.2. Installation

2.2.1. Maven

Add the DocOps extension dependency to your Maven project:

<dependency>
  <groupId>io.docops</groupId>
  <artifactId>docops-extension-server</artifactId>
  <version>2024.00</version>
</dependency>

2.2.2. Gradle

For Gradle projects, add the following to your build.gradle file:

implementation 'io.docops:docops-extension-server:2024.00'

2.3. Integration with AsciiDoctorJ

After adding the dependency to your project, you need to register the DocOps extensions with AsciiDoctorJ:

// In your Java code
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.jruby.extension.spi.ExtensionRegistry;

// Initialize AsciiDoctorJ with DocOps extensions
Asciidoctor asciidoctor = Asciidoctor.Factory.create();
// Register the DocOps extension
ExtensionRegistry.registerExtension(asciidoctor);

// Process your AsciiDoc content
String html = asciidoctor.convert(asciiDocContent, options);

3. Basic Usage

The DocOps extension uses a special block syntax in your AsciiDoc documents. The general format is:

[docops,kind="visualization_type"]

Your content here









Where visualization_type is the type of visualization you want to create (e.g., "adr", "buttons", "timeline", etc.).






3.1. Common Parameters




Most DocOps visualizations support these common parameters:












Parameter
Description







kind


The type of visualization (required)






title


Title for the visualization






useDark


Enable dark mode (true/false)






scale


Scaling factor for the output






role


Alignment (left/center/right)






controls


Show interactive controls (true/false)















4. Creating Visualizations






Let’s explore how to create different types of visualizations using the DocOps extension.






4.1. Architecture Decision Records (ADR)




ADRs help document important architectural decisions with their context, rationale, and consequences.








[docops,adr,useDark=false,role=center]
----
title: Use Elasticsearch for Search Functionality
status: Accepted
date: 2024-05-15
context:
- Our application needs robust search capabilities across multiple data types
- We need to support full-text search with relevance ranking
- The search functionality must scale with growing data volumes
- We need to support faceted search and filtering
decision:
- We will use Elasticsearch as our search engine
- We will integrate it with our existing PostgreSQL database
- We will implement a synchronization mechanism to keep data in sync
consequences:
- Improved search performance and capabilities
- Additional infrastructure to maintain
- Need for expertise in Elasticsearch configuration and optimization
- Potential complexity in keeping data synchronized
participants: Jane Smith (Architect), John Doe (Developer), Alice Johnson (Product Manager)
----








4.1.1. ADR Parameters










Parameter
Description







title


The main heading of the ADR (required)






status


Status of the decision: Proposed, Accepted, Superseded, Deprecated, or Rejected (required)






date


The date when the decision was made (required)






context


Factors that influenced the decision (required)






decision


The actual decision made (required)






consequences


Results of the decision (required)






participants


People involved in making the decision (optional)













4.2. Charts




The DocOps extension supports various chart types including bar charts, line charts, and pie charts.






4.2.1. Bar Chart Example






[docops,bar]
----
title=Monthly Sales Performance
yLabel=Revenue ($)
xLabel=Month
baseColor=#4cc9f0
type=R
---
January | 120.0
February | 334.0
March | 455.0
April | 244.0
May | 256.0
June | 223.0
----










4.2.2. Line Chart Example






[docops,line]
----
title=Department Performance
width=800
smooth=true
darkMode=false
---
Sales | Jan | 40
Sales | Feb | 70
Sales | Mar | 90
Sales | Apr | 70
Sales | May | 40
Sales | Jun | 30
Sales | Jul | 60
Sales | Aug | 90
Sales | Sept | 70
Marketing | Jan | 22
Marketing | Feb | 33
Marketing | Mar | 44
Marketing | Apr | 55
Marketing | May | 66
Marketing | Jun | 77
Marketing | Jul | 88
Marketing | Aug | 109
Marketing | Sept | 110
Development | Jan | 56
Development | Feb | 65
Development | Mar | 78
Development | Apr | 72
Development | May | 56
Development | Jun | 94
Development | Jul | 86
Development | Aug | 73
Development | Sept | 70
----












4.3. Badges & Shields




Create customizable status badges and shields for your documentation:








[docops,badge]
----
Made With|Kotlin||#06133b|#6fc441|<Kotlin>|#fcfcfc
JVM|Runtime||#acacac|#3B1E54|<Java>|#fcfcfc
AsciiDoctor|Documentation||#acacac|#4CC9FE|<asciidoctor>|#fcfcfc
----








The badge format is:
Label|Value||LeftColor|RightColor|IconReference|TextColor








4.4. Buttons




Create interactive buttons for navigation and actions:








[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Documentation",
      "link": "https://docops.io/docs",
      "description": "View documentation",
      "embeddedImage": {"ref": "images/docs.svg"}
    },
    {
      "label": "GitHub",
      "link": "https://github.com/docops-info",
      "description": "View source code",
      "embeddedImage": {"ref": "<GitHub>"}
    },
    {
      "label": "Support",
      "link": "https://docops.io/support",
      "description": "Get help",
      "embeddedImage": {"ref": "images/support.svg"}
    }
  ],
  "buttonType": "HEX",
  "theme": {"hexLinesEnabled": true,"strokeColor": "#7695FF","colors": ["#353d4b"],"scale": 1,"columns": 3}
}
----








4.4.1. Button Types




The DocOps extension supports different button types:






    

  • 

    HEX - Hexagonal buttons
    

    • 

  • 

    RECT - Rectangular buttons
    

    • 

  • 

    ROUND - Rounded buttons
    

    • 











4.5. Flow Connectors




Create flow diagrams and process maps:








[docops,connector,useDark=false]
----
{
  "connectors": [
    {"text": "Engineer","description": "Creates tests"},
    {"text": "Unit Tests","description": "Run Unit Tests"},
    {"text": "GitHub","description": "Upload to Github"},
    {"text": "Test Engine","description": "GitHub webhook plugged into engine"},
    {"text": "GitHub","description": "Results stored in Github"},
    {"text": "API Documentation","description": "API documentation ready for consumption"}
  ]
}
----










4.6. Placemat & Planner




Organize content with placemats:








[docops,placemat,useDark=false]
----
{
  "title": "System Architecture Overview",
  "placeMats": [
    {"name": "Frontend","legend": "UI"},
    {"name": "Backend","legend": "API"},
    {"name": "Database","legend": "DATA"}
  ],
  "config": {
  "legend": [
    {"legend": "UI","color": "#4361ee"},
    {"legend": "API","color": "#3a0ca3"},
    {"legend": "DATA","color": "#7209b7"}
  ]}
}
----










4.7. Project Planner




Create visual project planners with NOW/NEXT/LATER categories:








[docops,roadmap,useDark=false, title="Q3 Development Roadmap", scale="2.2"]
----
- now Authentication
* Implement user authentication system
* Set up CI/CD pipeline
* Create database schema
- next REST
* Develop REST API endpoints
* Build frontend components
* Implement search functionality
- later Analytics
* Add analytics dashboard
* Optimize performance
* Implement advanced features
- done Requirements
* Project requirements gathering
* Architecture design
* Technology stack selection
----










4.8. Release Strategy




Visualize release plans and deployment strategies:








[docops,release]
----
{
  "title": "Product Release Strategy",
  "style": "TLS", "scale": 0.5,
  "releases": [
    {
      "type": "M1",
      "date": "2023-01-15",
      "goal": "Initial Planning",
      "lines": [
        "Define release scope and objectives",
        "Identify key features and enhancements",
        "Create detailed project timeline",
        "Allocate resources and responsibilities"
      ]
    },
    {
      "type": "M2",
      "date": "2023-02-15",
      "goal": "Development Phase",
      "lines": [
        "Code development and unit testing",
        "Integration of components",
        "Documentation updates",
        "Internal code reviews"
      ]
    },
    {
      "type": "RC1",
      "date": "2023-03-15",
      "goal": "Testing Phase",
      "lines": [
        "Functional testing",
        "Performance testing",
        "Security testing",
        "User acceptance testing"
      ]
    },
    {
      "type": "GA",
      "date": "2023-04-15",
      "goal": "Deployment Phase",
      "lines": [
        "Final approval and sign-off",
        "Production deployment",
        "Post-deployment verification",
        "Monitoring and support"
      ]
    }
  ]
}
----










4.9. Scorecard




Create visual scorecards for comparison:








[docops,scorecard]
----
{
  "title": "Technology Comparison",
  "initiativeTitle": "Current Solution",
  "outcomeTitle": "Proposed Solution",
  "initiativeItems": [
    {"displayText":"Limited scalability"},
    {"displayText":"High maintenance costs"},
    {"displayText":"Manual deployment process"},
    {"displayText":"Minimal monitoring capabilities"},
    {"displayText":"Difficult to extend"}
  ],
  "outcomeItems": [
    {"displayText":"Highly scalable architecture"},
    {"displayText":"Reduced operational costs"},
    {"displayText":"Automated CI/CD pipeline"},
    {"displayText":"Comprehensive monitoring"},
    {"displayText":"Modular and extensible design"}
  ]
}
----










4.10. Timeline




Create interactive timelines for project history and planning:








[docops,timeline,title="Project Timeline",scale="1",role="center"]
----
-
date: 2023-01-15
text: Project kickoff meeting
-
date: 2023-02-01
text: Requirements gathering completed
-
date: 2023-03-15
text: Design phase completed
-
date: 2023-04-30
text: Development phase started
-
date: 2023-06-15
text: Alpha release
-
date: 2023-08-01
text: Beta testing
-
date: 2023-09-15
text: Production release
----














5. Advanced Features






5.1. Interactive Controls




Add interactive controls to your visualizations:








[docops,kind="buttons",controls=true,copy=true,zoom=true,expand=true]
----
Your content here
----








The controls parameter adds a floating control panel with:






    

  • 

    Zoom in/out buttons
    

    • 

  • 

    Copy as SVG/PNG options
    

    • 

  • 

    Fullscreen toggle
    

    • 









5.2. Dark Mode Support




Most visualizations support dark mode:








[docops,kind="adr",useDark=true]
----
Your content here
----










5.3. Custom Styling




Many visualizations support custom styling options:








[docops,buttons]
----
{
  "buttons": [...],
  "theme": {
    "colors": ["#353d4b", "#4361ee"],
    "strokeColor": "#7695FF",
    "scale": 1.2
  }
}
----














6. Best Practices






6.1. Performance Optimization




    

  • 

    Use appropriate scale values to balance quality and file size
    

    • 

  • 

    Consider PDF-specific optimizations for print output
    

    • 

  • 

    Limit the number of complex visualizations per page
    

    • 









6.2. Accessibility




    

  • 

    Provide meaningful title attributes
    

    • 

  • 

    Use sufficient color contrast in custom themes
    

    • 

  • 

    Ensure keyboard navigation works with interactive controls
    

    • 









6.3. Documentation Structure




    

  • 

    Group related visualizations together
    

    • 

  • 

    Provide context and explanation around visualizations
    

    • 

  • 

    Use consistent styling across similar visualization types
    

    • 













7. Troubleshooting






7.1. Common Issues











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











7.2. Debug Mode




Enable debug logging by setting the document attribute:








:local-debug: true










7.3. Server Configuration




You can override the default server URL by setting document attributes:








:panel-server: http://your-custom-server:8080/extension
:panel-webserver: http://your-custom-webserver:8080














8. Conclusion






The DocOps Extension Server provides a powerful way to enhance your AsciiDoctor documents with interactive visualizations. By following this tutorial, you should now be able to create a variety of visualizations to improve your documentation.






For more detailed information on specific visualization types, refer to the dedicated documentation below:











DocOps.ioMIT Licensehttps://docops.io2025-06-21Generated by DocOps.io - Licensed under MIT License            TitleADRBar ChartsButtonsCalloutChartsConnectorsDocOps CoreExamplesLine ChartsMetrics CardPie ChartsPlacematPlannerQuadrantRelease StrategyScorecardShieldSwimlaneTimelineTree ChartWord Cloud











Happy documenting!