Introduction

The DocOps Bar Chart Extension allows you to create visually appealing bar charts in your AsciiDoctor documents. Bar charts are useful for comparing data across categories and visualizing trends over time.

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

Basic Concepts

What are Bar Charts?

Bar charts in the DocOps extension are SVG-based graphical elements that can be included in your AsciiDoctor documents. Each bar chart has:

  • A title (the main heading of the chart)

  • X and Y axis labels

  • A series of data points (bars)

  • Optional display settings for customizing the appearance

The extension supports two main types of bar charts:

  • Regular Bar Charts - For comparing individual data points

  • Grouped Bar Charts - For comparing multiple data series across categories

Each type can be displayed in various styles, including:

  • Horizontal bars

  • Vertical bars

  • Cylinder-style bars

  • Dark mode charts

Bar Chart Components

Regular Bar Charts

A regular bar chart includes:

  • A title

  • X and Y axis labels

  • A series of data points, each with a label and value

  • Display settings for visual appearance

Grouped Bar Charts

A grouped bar chart includes:

  • A title

  • X and Y axis labels

  • Multiple groups, each containing a series of data points

  • Display settings for visual appearance

AsciiDoctor Syntax for Bar Charts

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

[docops,bar]
----
title=Chart Title
yLabel=Y-Axis Label
xLabel=X-Axis Label
baseColor=#4361ee
vBar=false
useDark=false
type=R
---
Category 1 | 120.0
Category 2 | 334.0
// More data points...
----

For grouped bar charts, use the following format:

[docops,bargroup]
----
title=Chart Title
yLabel=Y-Axis Label
xLabel=X-Axis Label
baseColor=#D988B9
vBar=false
condensed=false
useDark=false
---
Group 1 | Category 1 | 5000.0
Group 1 | Category 2 | 7000.0
// More data points...
Group 2 | Category 1 | 6000.0
Group 2 | Category 2 | 8000.0
// More data points...
// More groups...
----

The macro processes the configuration and data and generates an SVG representation of the bar chart that is embedded in your document.

Regular Bar Chart Properties

Configuration Properties

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

  • yLabel (optional): The label for the Y-axis

  • xLabel (optional): The label for the X-axis

  • baseColor (optional): The base color for the bars (default: "#FE7A36")

  • type (optional): The style of the bars ("R" for regular, "C" for cylinder)

  • vBar (optional): Whether to display vertical bars (default: false)

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

  • sorted (optional): Whether to sort the bars by value (default: false)

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

Data Format

After the configuration section and the separator line (---), each line represents a data point with the following format:

Label | Value [| Color]

  • Label (required): The category label for the data point

  • Value (required): The numerical value for the data point

  • Color (optional): A custom color for this specific data point

Grouped Bar Chart Properties

Configuration Properties

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

  • yLabel (optional): The label for the Y-axis

  • xLabel (optional): The label for the X-axis

  • baseColor (optional): The base color for the chart (default: "#D988B9")

  • lineColor (optional): The color for grid lines (default: "#FFBB5C")

  • vBar (optional): Whether to display vertical bars (default: false)

  • condensed (optional): Whether to use condensed mode (default: false)

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

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

Data Format

After the configuration section and the separator line (---), each line represents a data point with the following format:

Group | Label | Value [| Color]

  • Group (required): The name of the group

  • Label (required): The category label for the data point

  • Value (required): The numerical value for the data point

  • Color (optional): A custom color for this specific data point

Examples

Basic Bar Chart Example

Here’s a simple example of a horizontal bar chart:

[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
----
DocOps.ioMIT Licensehttps://docops.io2025-06-21Generated by DocOps.io - Licensed under MIT License0255075100Revenue ($)January120February334March455April244May256June223MonthMonthly Sales Performance

Vertical Bar Chart Example

You can create vertical bar charts by setting the vBar property to true:

[docops,bar,controls=true]
----
title=Berry Picking by Month 2024
yLabel=Number of Sales
xLabel=Month
baseColor=#4361ee
vBar=true
---
Jan | 120.0
Feb | 334.0
Mar | 455.0
Apr | 244.0
May | 256.0
Jun | 223.0
----
DocOps.ioMIT Licensehttps://docops.io2025-06-21Generated by DocOps.io - Licensed under MIT License0255075100Number of SalesJan120Feb334Mar455Apr244May256Jun223MonthBerry Picking by Month 2024

Cylinder-Style Bar Chart Example

You can create cylinder-style bar charts by setting the type property to "C":

[docops,bar,controls=true]
----
title=Quarterly Performance
yLabel=Revenue ($)
xLabel=Quarter
baseColor=#f72585
type=C
---
Q1 | 320.0
Q2 | 480.0
Q3 | 290.0
Q4 | 410.0
----
320 Q1 480 Q2 290 Q3 410 Q4 Revenue ($) Quarter Quarterly Performance Revenue ($) 260 280 300 320 340 360 380 400 420 440Quarter

Dark Mode Bar Chart Example

You can create dark mode bar charts by setting the useDark property to true:

[docops,bar,controls=true]
----
title=Monthly Sales Performance (Dark Mode)
yLabel=Revenue ($)
xLabel=Month
baseColor=#4cc9f0
useDark=true
type=R
---
January | 120.0
February | 334.0
March | 455.0
April | 244.0
May | 256.0
June | 223.0
----
DocOps.ioMIT Licensehttps://docops.io2025-06-21Generated by DocOps.io - Licensed under MIT License0255075100Revenue ($)January120February334March455April244May256June223MonthMonthly Sales Performance (Dark Mode)

Grouped Bar Chart Example

Here’s an example of a grouped bar chart:

[docops,bargroup,controls=true]
----
title=Annual Product Sales Report
yLabel=Sales (USD)
xLabel=Quarters
lineColor=#921A40
baseColor=#F3EDED
---
Product A | Q1 | 5000.0
Product A | Q2 | 7000.0
Product A | Q3 | 8000.0
Product A | Q4 | 6000.0
Product B | Q1 | 6000.0
Product B | Q2 | 8000.0
Product B | Q3 | 7000.0
Product B | Q4 | 9000.0
----
DocOps.ioMIT Licensehttps://docops.io2025-06-21Generated by DocOps.io - Licensed under MIT LicenseAnnual Product Sales ReportQuartersSales (USD)5.0k7.0k8.0k6.0kProductA6.0k8.0k7.0k9.0kProductB 5.0k 5.5k 6.0k 6.5k 7.0k 7.5k 8.0k 8.5kQ1Q2Q3Q4

Vertical Grouped Bar Chart Example

You can create vertical grouped bar charts by setting the vBar property to true:

[docops,bargroup,controls=true]
----
title=Annual Product Sales Report
yLabel=Sales (USD)
xLabel=Quarters
lineColor=#921A40
baseColor=#F3EDED
vBar=true
---
Product A | Q1 | 5000.0
Product A | Q2 | 7000.0
Product A | Q3 | 8000.0
Product A | Q4 | 6000.0
Product B | Q1 | 6000.0
Product B | Q2 | 8000.0
Product B | Q3 | 7000.0
Product B | Q4 | 9000.0
----
DocOps.ioMIT Licensehttps://docops.io2025-06-21Generated by DocOps.io - Licensed under MIT LicenseAnnual Product Sales ReportQuartersSales (USD)Product A5.0kQ17.0kQ28.0kQ36.0kQ4Product B6.0kQ18.0kQ27.0kQ39.0kQ4LegendQ1Q2Q3Q4

Condensed Grouped Bar Chart Example

You can create condensed grouped bar charts by setting the condensed property to true:

[docops,bargroup,controls=true]
----
title=Annual Product Sales Report
yLabel=Sales (USD)
xLabel=Quarters
lineColor=#921A40
baseColor=#F3EDED
condensed=true
---
Product A | Q1 | 5000.0
Product A | Q2 | 7000.0
Product A | Q3 | 8000.0
Product A | Q4 | 6000.0
Product B | Q1 | 6000.0
Product B | Q2 | 8000.0
Product B | Q3 | 7000.0
Product B | Q4 | 9000.0
----
DocOps.ioMIT Licensehttps://docops.io2025-06-21Generated by DocOps.io - Licensed under MIT LicenseAnnual Product Sales Report QuartersSales (USD)7501.5k2.3k3.0k3.8k4.5k5.3k6.0kProduct A5.0k7.0k8.0k6.0kProduct B6.0k8.0k7.0k9.0kLegend Q1Q2Q3Q4

Conclusion

The DocOps Bar Chart Extension provides a powerful way to enhance your AsciiDoctor documents with visually appealing bar charts. By using the simple key-value configuration format and pipe-separated data, you can create customized charts that match your document’s style and purpose.

The extension supports both regular and grouped bar charts, with various display options including horizontal/vertical orientation, cylinder style, dark mode, and condensed mode for grouped charts.