DocOps Place Mats

1. Introduction

The DocOps Place mat Extension allows you to create visually appealing grid-based diagrams in your AsciiDoctor documents. Place mats are useful for organizing related concepts, showing system components, or presenting categorized information in a structured layout.

This guide will help you understand the basic concepts of place mats, how to include them in your AsciiDoctor documents, and provide examples of different types of place mats.

2. Basic Concepts

2.1. What are Place mats?

Place mats in the DocOps extension are SVG-based graphical elements that can be included in your AsciiDoctor documents. Each place mat has:

  • A title (the main heading of the diagram)

  • A grid of boxes, each containing text

  • A legend that categorizes the boxes by color

  • Optional display settings for customizing the appearance

The extension supports different display options, including:

  • Regular mode (light background)

  • Dark mode (dark background)

  • Filled or outlined boxes

  • Different scaling options

2.2. Place mat Components

A place mat diagram includes:

  • A title at the top

  • A grid of boxes, each containing text

  • Color-coding based on categories

  • A legend explaining the color categories

3. AsciiDoctor Syntax for Place mats

To include place mats in your AsciiDoctor document, you use a special macro syntax. Here’s the basic format:

[docops,placemat]
----
{
  "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"}
    ]
  }
}
----

The macro processes the JSON configuration and generates an SVG representation of the place mat that is embedded in your document.

3.1. Place mat Properties

3.1.1. Main Properties

  • title (required): The main heading of the diagram

  • placeMats (required): An array of placemat box objects

  • config (required): Configuration settings for the placemat

  • useDark (optional): Whether to use dark mode (default: false)

  • scale (optional): A scaling factor for the diagram (default: 1.0)

  • fill (optional): Whether to use filled boxes (default: true)

3.1.2. PlaceMat Box Properties

Each box in the placeMats array has the following properties:

  • name (required): The text displayed inside the box

  • legend (required): The category of the box (must match a legend entry)

  • style (optional): Custom CSS styling for this specific box

3.1.3. Config Properties

The config object has the following properties:

  • legend (required): An array of legend configuration objects

  • style (optional): Global CSS styling for the placemat

3.1.4. Legend Configuration Properties

Each legend configuration in the legend array has the following properties:

  • legend (required): The name of the category

  • color (required): The color code for the category

  • style (optional): CSS styling for the legend item

4. Examples

4.1. Basic Placemat Example

Here’s a simple example of a place mat diagram:

[docops,placemat]
----
{
  "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"}
    ]
  }
}
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License System Architecture OverviewFrontendBackendDatabaseLegendUIAPIDATA

4.2. Technology Stack Example

This example illustrates a technology stack with different categories:

[docops,placemat]
----
{
  "title": "Modern Web Development Stack",
  "placeMats": [
    {"name": "React", "legend": "Frontend"},
    {"name": "Vue.js", "legend": "Frontend"},
    {"name": "Angular", "legend": "Frontend"},
    {"name": "Node.js", "legend": "Backend"},
    {"name": "Express", "legend": "Backend"},
    {"name": "Spring Boot", "legend": "Backend"},
    {"name": "MongoDB", "legend": "Database"},
    {"name": "PostgreSQL", "legend": "Database"},
    {"name": "Redis", "legend": "Database"},
    {"name": "Docker", "legend": "DevOps"},
    {"name": "Kubernetes", "legend": "DevOps"},
    {"name": "Jenkins", "legend": "DevOps"},
    {"name": "AWS", "legend": "Cloud"},
    {"name": "Azure", "legend": "Cloud"},
    {"name": "Google Cloud", "legend": "Cloud"}
  ],
  "config": {
    "legend": [
      {"legend": "Frontend", "color": "#4cc9f0"},
      {"legend": "Backend", "color": "#4361ee"},
      {"legend": "Database", "color": "#3a0ca3"},
      {"legend": "DevOps", "color": "#7209b7"},
      {"legend": "Cloud", "color": "#f72585"}
    ]
  }
}
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Modern Web Development StackReactVue.jsAngularNode.jsExpressSpringBootMongoDBPostgreSQLRedisDockerKubernetesJenkinsAWSAzureGoogleCloudLegendFrontendBackendDatabaseDevOpsCloud

4.3. Dark Mode Placemat Example

You can create dark mode placemats by setting the useDark parameter to true:

[docops,placemat]
----
{
  "title": "Software Development Lifecycle",
  "useDark": true,
  "placeMats": [
    {"name": "Requirements", "legend": "Planning"},
    {"name": "Design", "legend": "Planning"},
    {"name": "Implementation", "legend": "Development"},
    {"name": "Testing", "legend": "Quality"},
    {"name": "Deployment", "legend": "Operations"},
    {"name": "Maintenance", "legend": "Operations"},
    {"name": "User Feedback", "legend": "Feedback"},
    {"name": "Iteration Planning", "legend": "Planning"}
  ],
  "config": {
    "legend": [
      {"legend": "Planning", "color": "#4cc9f0"},
      {"legend": "Development", "color": "#4361ee"},
      {"legend": "Quality", "color": "#3a0ca3"},
      {"legend": "Operations", "color": "#7209b7"},
      {"legend": "Feedback", "color": "#f72585"}
    ]
  }
}
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Software Development LifecycleRequirementsDesignImplementationTestingDeploymentMaintenanceUserFeedbackIterationPlanningLegendPlanningDevelopmentQualityOperationsFeedback

4.4. Outlined Boxes Example

You can create place mats with outlined boxes by setting the fill parameter to false:

[docops,placemat]
----
{
  "title": "Data Science Workflow",
  "fill": false,
  "placeMats": [
    {"name": "Data Collection", "legend": "Data"},
    {"name": "Data Cleaning", "legend": "Data"},
    {"name": "Exploratory Analysis", "legend": "Analysis"},
    {"name": "Feature Engineering", "legend": "Analysis"},
    {"name": "Model Selection", "legend": "Modeling"},
    {"name": "Model Training", "legend": "Modeling"},
    {"name": "Model Evaluation", "legend": "Evaluation"},
    {"name": "Model Deployment", "legend": "Deployment"}
  ],
  "config": {
    "legend": [
      {"legend": "Data", "color": "#06d6a0"},
      {"legend": "Analysis", "color": "#1b9aaa"},
      {"legend": "Modeling", "color": "#ef476f"},
      {"legend": "Evaluation", "color": "#ffd166"},
      {"legend": "Deployment", "color": "#073b4c"}
    ]
  }
}
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Data Science WorkflowDataCollectionDataCleaningExploratoryAnalysisFeatureEngineeringModelSelectionModelTrainingModelEvaluationModelDeploymentLegendDataAnalysisModelingEvaluationDeployment

4.5. Enterprise Architecture Example

This example illustrates an enterprise architecture with different domains:

[docops,placemat]
----
{
  "title": "Enterprise Architecture Domains",
  "placeMats": [
    {"name": "Business Strategy", "legend": "Business"},
    {"name": "Business Processes", "legend": "Business"},
    {"name": "Organization Structure", "legend": "Business"},
    {"name": "Application Portfolio", "legend": "Application"},
    {"name": "Application Integration", "legend": "Application"},
    {"name": "User Experience", "legend": "Application"},
    {"name": "Data Models", "legend": "Data"},
    {"name": "Data Governance", "legend": "Data"},
    {"name": "Data Quality", "legend": "Data"},
    {"name": "Infrastructure", "legend": "Technology"},
    {"name": "Security", "legend": "Technology"},
    {"name": "Cloud Strategy", "legend": "Technology"}
  ],
  "config": {
    "legend": [
      {"legend": "Business", "color": "#ff9e00"},
      {"legend": "Application", "color": "#ff5500"},
      {"legend": "Data", "color": "#e10600"},
      {"legend": "Technology", "color": "#8900f2"}
    ]
  }
}
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Enterprise Architecture DomainsBusinessStrategyBusinessProcessesOrganizationStructureApplicationPortfolioApplicationIntegrationUserExperienceDataModelsDataGovernanceDataQualityInfrastructureSecurityCloudStrategyLegendBusinessApplicationDataTechnology

4.6. Combining Place mats with Connectors

You can use placemats to show components and then use connectors to illustrate the flow between them:

First, create a placemat to show the components:

[docops,placemat]
----
{
  "title": "Microservices Architecture",
  "placeMats": [
    {"name": "API Gateway", "legend": "Gateway"},
    {"name": "User Service", "legend": "Service"},
    {"name": "Product Service", "legend": "Service"},
    {"name": "Order Service", "legend": "Service"},
    {"name": "Payment Service", "legend": "Service"},
    {"name": "User Database", "legend": "Database"},
    {"name": "Product Database", "legend": "Database"},
    {"name": "Order Database", "legend": "Database"},
    {"name": "Payment Database", "legend": "Database"}
  ],
  "config": {
    "legend": [
      {"legend": "Gateway", "color": "#4cc9f0"},
      {"legend": "Service", "color": "#4361ee"},
      {"legend": "Database", "color": "#3a0ca3"}
    ]
  }
}
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Microservices ArchitectureAPIGatewayUserServiceProductServiceOrderServicePaymentServiceUserDatabaseProductDatabaseOrderDatabasePaymentDatabaseLegendGatewayServiceDatabase

Then, use connectors to show the flow between components:

[docops,connector]
----
{
  "connectors": [
    {
      "text": "API Gateway",
      "baseColor": "#4cc9f0",
      "description": "Entry point for all client requests"
    },
    {
      "text": "User Service",
      "baseColor": "#4361ee",
      "description": "Handles user authentication and profiles"
    },
    {
      "text": "User Database",
      "baseColor": "#3a0ca3",
      "description": "Stores user information"
    }
  ]
}
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License APIGatewayA UserServiceB UserDatabaseCAEntry point for all client requestsBHandles user authentication and profilesCStores user information 
[docops,connector]
----
{
  "connectors": [
    {
      "text": "API Gateway",
      "baseColor": "#4cc9f0",
      "description": "Entry point for all client requests"
    },
    {
      "text": "Product Service",
      "baseColor": "#4361ee",
      "description": "Manages product catalog"
    },
    {
      "text": "Product Database",
      "baseColor": "#3a0ca3",
      "description": "Stores product information"
    }
  ]
}
----
[docops,connector]
----
{
  "connectors": [
    {
      "text": "API Gateway",
      "baseColor": "#4cc9f0",
      "description": "Entry point for all client requests"
    },
    {
      "text": "Order Service",
      "baseColor": "#4361ee",
      "description": "Handles order processing"
    },
    {
      "text": "Payment Service",
      "baseColor": "#4361ee",
      "description": "Processes payments"
    }
  ]
}
----

5. Conclusion

The DocOps Place mat Extension provides a powerful way to enhance your AsciiDoctor documents with visually appealing grid-based diagrams. By using the JSON configuration format, you can create customized place mats that organize and categorize information in a structured layout.

The extension supports both regular and dark mode displays, with various customization options for colors, fill styles, and scaling.