Plotance Guide

In a nutshell

Plotance is a cross-platform command-line tool converting Markdown with SQL into plain editable PowerPoint presentations with charts, powered by DuckDB.

Markdown documents are segmented into slides based on headings. Each slide is divided into rows and each row is divided into columns, which display either Markdown blocks or charts. Column count and sizing are specified with option blocks within the Markdown.

You can configure slides, charts, and queries using either special code blocks containing YAML or XML processing instructions. These two notation methods are functionally equivalent and interchangeable.

For an overview of features and syntax, please refer to the Examples page.

Installation, invocation, and uninstallation

Plotance is a single binary executable that can be put in an arbitrary location and run from the command line. For more details, please refer to the Downloads page.

At its simplest, you only need to specify an input filename. In the example below, slide.pptx will be generated:

Windows:

.\plotance slide.md

Linux or macOS:

./plotance slide.md

To uninstall, remove the executable file along with the following folders:

Linux or macOS: $HOME/.net/plotance
Windows: %TEMP%/.net/plotance

If the environment variable DOTNET_BUNDLE_EXTRACT_BASE_DIR is defined, remove the plotance directory under it instead.

Building from source

To build and run from source, follow these steps:

git clone https://github.com/plotance/plotance.git
cd plotance
dotnet build
dotnet Plotance/bin/Release/net8.0/plotance.dll --version

To create a single binary executable, use the following commands:

dotnet publish
./Plotance/bin/Release/net8.0/linux-x64/publish/plotance --version

Run create_release_archives.ps1 in PowerShell to create release ZIP archives for all platforms.

Command line options

The command line takes the following form:

plotance [OPTION]... INPUT.md

OPTION is a list of command-line options, described in the following table:

Option	Description
`-o`, `--output=OUTPUT.pptx`	Output filename. Defaults to the input filename with the extension changed to `.pptx`.
`--template=TEMPLATE.pptx`	Template .pptx file.
`--db-config=NAME=VALUE`	DuckDB options.
`--arg`, `--argument=NAME=VALUE`	Parameter values. Can be referenced in SQL using the `getvariable` function. In Markdown, use `${NAME}` syntax.
`-v`, `--verbose`, `--verbosity=[LEVEL]`	Specifies the log level. Possible values: `Quiet`, `Q`, `Minimal`, `M`, `Normal`, `N`, `Detailed`, `D`, `Diagnostic`, `Diag`. All values except `Diagnostic` and `Diag` are equivalent. If `LEVEL` is omitted, defaults to `Diagnostic`.
`--version`	Display version information.
`--help`	Display help information.

Plotance Markdown

Plotance uses Markdown to represent slides. There are some special rules, syntax, and limitations to be aware of.

Splitting Document into Slides

Documents are segmented into slides using headings or thematic breaks (horizontal rules). A heading creates a slide break when its level is less than or equal to the value of slide_level option. The behavior varies depending on this value:

With slide_level: 1:
- Level 1 headings: Start a regular slide.
- Level 2+ headings: Treated as regular text blocks within the slide.
With slide_level: 2 (default):
- Level 1 headings: Start a title slide.
- Level 2 headings: Start a regular slide.
- Level 3+ headings: Treated as regular text blocks within the slide.
With slide_level: 3:
- Level 1 headings: Start a title slide.
- Level 2 headings: Start a section title slide.
- Level 3 headings: Start a regular slide.
- Level 4+ headings: Treated as regular text blocks within the slide.

Layout inside Slides

Each slide is structured with rows and columns. You can control the number of columns and their relative widths using the columns option. This option can be specified independently for each row.

For instance, columns: 1:2:1 designates three columns with widths in a 1:2:1 ratio. You can also specify absolute dimensions alongside ratios. With columns: 1cm:2:1, the first column is fixed at 1 cm wide, while the remaining space is divided in a 2:1 ratio between the other columns.

Similarly, you can use the rows option to specify height ratios or lengths for rows.

Both columns and rows options are reset for each slide.

Content blocks are classified as either visible or invisible. Only visible blocks are counted as columns. The following elements are treated as invisible (all others are visible):

HTML comments
HTML DOCTYPE declaration
HTML processing instructions
Config blocks without queries
Config blocks with queries and format: none

Example: The following will split the slide vertically in a 3:1 ratio and horizontally in a 1:3:1 ratio:

<?plotance rows: 3:1 ?>
<?plotance columns: 1:3:1 ?>

row 1 column 1

row 1 column 2

row 1 column 3

row 2 column 1

row 2 column 2

row 3 column 3

Example: The following will create a single column in the first row and three columns in the second row:

<?plotance rows: 3:1 ?>
<?plotance columns: 1 ?>

row 1 column 1

<?plotance columns: 1:3:1 ?>

row 2 column 1

row 2 column 2

row 2 column 3

Restrictions

While Plotance accepts the CommonMark documents, it has certain restrictions imposed by PowerPoint's underlying architecture:

Blocks cannot be nested within other blocks. Nested lists are allowed as an exception.
Images can be used only in the following cases; general inline images are not supported:
- As the only child element of a top-level paragraph.
- As the only child element of a link that is the only child element of a top-level paragraph.
General HTML elements cannot be embedded.

Option blocks

Configuration options for charts and global Plotance settings can be embedded using either code blocks or XML processing instructions. All options are parsed as YAML. For example:

```plotance
slide_level: 1
db_config:
  http_proxy: https://proxy.example.com/
template: template.pptx
parameters:
  - name: year
    description: Report year (yyyy).
    default: 2025
  - name: month
    description: Report month (MM).
    default: 01
```

<?plotance rows: 3:1 ?>

```plotance
format: bar
query_file: query.sql
query: |
  SELECT * FROM 'data.csv'
```

Options specified alongside query or query_file apply only to that specific block. All other options remain in effect throughout the document unless explicitly mentioned.

For details of options, please refer to the options reference.

Single-line XML processing instructions are automatically enclosed in { and } braces if not already present. The following examples are all equivalent:

<?plotance rows: 3:1, columns: 1:3:1 ?>

<?plotance { rows: 3:1, columns: 1:3:1 } ?>

```plotance
rows: 3:1
columns: 1:3:1
```

In multi-line XML processing instructions, Plotance automatically removes the minimum indentation from the second line onward (empty lines are excluded from this calculation). These examples are all equivalent:

<?plotance
  rows: 3:1
  columns: 1:3:1
?>

<?plotance rows: 3:1
           columns: 1:3:1 ?>

```plotance
rows: 3:1
columns: 1:3:1
```

Option blocks only take effect when they appear at the top level of the document.

Parameters

Parameters are variables that can be referenced from the document, option blocks, and queries. You can define parameter values either through the command-line option --arg or the parameters option within the document. Command-line parameters take precedence over document-defined parameters with the same name. When multiple definitions for the same parameter name exist within a document, only the first definition is applied.

Example of parameters option:

```plotance
parameters:
  - name: year
    description: The year of charts.
    default: 2025
  - name: month
    description: The month of charts.
    default: 01
```

Parameters can be used in the following places:

In Markdown text. Syntax: ${name}
In YAML of option blocks. Syntax: ${name}
In SQL statements. Syntax: getvariable('name')

Within Markdown text and YAML option blocks, parameters are referenced using the ${name} syntax. During processing, these references are replaced with the actual value of the parameter named name. This substitution happens after the parsing of Markdown and YAML, so the expanded text is not re-interpreted as Markdown or YAML. Parameter references are not processed recursively. However, default values defined in the parameters section do support parameter expansion like other YAML values. Any references to undefined parameters remain as literal text in the output.

A special parameter named $ expands to the string $.

Template Files

Plotance supports using an existing PowerPoint file (.pptx) as a template. When you specify a template, Plotance creates a copy, removes all existing slides, and inserts the newly generated slides based on your Markdown content. The system utilizes the following slide layouts from the template's first slide master:

Title Slide
Title and Content
Section Header

Technical Details

Plotance picks slide layouts where the sldLayout element has a type attribute of title, obj, or secHead. If these specific layouts aren't present in the template, Plotance falls back to default layouts.

Headings are placed in placeholders where the ph element has a type attribute of either ctrTitle or title.

All other content is inserted into placeholders that either have an index attribute of 1 or a type attribute of obj, chart, dgm, tbl, subTitle, or body.

Chart formats

Chart formats are specified using the format option. The following formats are currently supported:

bar: Bar chart (vertical/horizontal)
scatter: Scatter plot, line chart
bubble: Bubble chart
area: Area chart
table: Table
combination: Combination chart (not implemented yet)
small_multiple: Small multiple (not implemented yet)
none: Do not output anything

Each chart format requires a specific query result structure. The sections below describe each format and its corresponding expected query result format.

`bar`

Visualizes values for each category as the height of rectangular bars. For multiple data series, bars are displayed side by side within each category group.

Expected query result format: Category Name,Series 1 Value,Series 2 Value,...

Specific options for bar charts (for other options, refer to the options reference):

bar_direction: Bar direction. Either horizontal or vertical. Default is vertical.
bar_grouping: Bar grouping method. One of clustered (side by side), stacked (stacked vertically), or percent_stacked (stacked vertically as percentages of the total). Default is clustered.
bar_gap: Specifies the gap between bar groups as a percentage of the bar width. Must be between 0 and 500.
bar_overlap: Specifies how much bars within the same group overlap, as a percentage of the bar width. Must be between -100 and 100.

`scatter`

Visualizes Y-coordinate values against X-coordinate values as positions of points on a plane. Points belonging to the same series can optionally be connected with lines.

Expected query result format: X-coordinate Value,Series 1 Y-coordinate Value,Series 2 Y-coordinate Value,...

To connect points with lines, set the line_width parameter to any value greater than 0.

Control the size of data points using the marker_size parameter. Setting this to 0 hides the markers entirely, showing only the connecting lines if enabled.

`line`

Visualizes changes in Y-coordinate values across X-coordinate values using connected lines. While visually appearing as a line chart, this is technically implemented as a scatter plot with modified defaults rather than PowerPoint's native line chart. The differences from the standard scatter plot are:

The default value of line_width is 1pt instead of 0.
The default values of x_axis_range_minimum and x_axis_range_maximum are the minimum and maximum values of the X-axis values.

Expected query result format: X-coordinate Value,Series 1 Y-coordinate Value,Series 2 Y-coordinate Value,...

Why we don't use PowerPoint's native line chart: PowerPoint's built-in line chart functions more like a bar chart internally, restricting X-axis values to categories or dates. For proper data visualization, a line chart's X-axis should be continuous quantitative values. For categorical X-axis data, a bar chart is generally more appropriate, while for quantitative X-axis data, a scatter plot provides better representation. A rare exception where categorical X-axis line charts make sense is when the visualization can be interpreted as multiple slope charts connected horizontally. In most scenarios, however, using one or more bar charts or scatter plots yields more accurate visualizations.

`bubble`

Visualizes triples of X-coordinate, Y-coordinate, and scalar values as positions and areas of bubbles.

Expected query result format: X-coordinate Value,Series 1 Y-coordinate Value,Series 1 Bubble Area,Series 2 Y-coordinate Value,Series 2 Bubble Area,...

`area`

Visualizes how the sum of values changes across categories or dates using the width of stacked bands.

Expected query result format: Category Name,Series 1 Value,Series 2 Value,...

Note: X-axis values are always treated as categories or dates, and the chart is always displayed in stacked format. This chart type is suited for showing how totals change across categories or dates. For other cases, consider bar charts or scatter plots instead.

`table`

Presents query results as a PowerPoint table instead of a graphical chart.

Expected query result format: Any.

For table formatting, refer to the options reference.

`none`

Executes the query without displaying any visual output and doesn't contribute to column count. This is useful for database operations like creating temporary tables, inserting records, or other preparatory SQL that doesn't need visualization.

Markdown Support Details

Block-Level Elements

Horizontal rules: Implemented as page breaks.
Headings: Function as page breaks based on the slide_level setting.
Code blocks (except Plotance option blocks): Rendered as fixed-width font blocks.
HTML comments: Ignored.
Other HTML blocks: Not supported.
Link reference definitions: Supported.
Paragraphs: Supported.
Quote blocks: Rendered as standard text blocks without special formatting.
Lists: Partially supported. Each list item may contain at most one paragraph followed optionally by one sublist, with this specific ordering requirement.
Tables: Limited support planned for future releases.
Other non-CommonMark elements: Not supported.

Inline-Level Elements

Code spans: Supported.
Emphasis: Supported.
Links: Supported.
Images: Supported in two specific cases: (1) when an image is the only content within a top-level paragraph, or (2) when an image is the only content of a link that is itself the only content of a top-level paragraph.
Automatic links: Supported.
Raw HTML: Not supported.
Hard line breaks: Supported.
Soft line breaks: Supported and rendered as a standard whitespace.
Other non-CommonMark elements: Not supported.

License

Plotance is released under the MIT License.