pelican-tabular

Pelican plugin to embed data tables in Markdown articles via a {% table %} shortcode.

Installation

uv add pelican-tabular

Add to pelicanconf.py:

PLUGINS = ["pelican.plugins.tabular"]

Usage

{% table data/books.yaml %}
{% table data/books.yaml fields="title,rating,year" %}
{% table data/books.yaml sort_by="rating" sort_order="desc" %}
{% table data/books.yaml hidden="internal_id" %}
{% table data/books.yaml group_by="genre" group_summary_at="genre" %}
{% table data/books.yaml group_by="author,year" aggregate="year:year" field_labels="year:Publication Year" %}
{% table data/books.yaml sort_by="date" date_format="%b %Y" %}
{% table data/books.yaml group_by="date:year" group_summary_at="date:year" %}
{% table data/books.yaml aria_columns="slide,recording" %}

Shortcode parameters

Data formats

Supports YAML (list of dicts), JSON arrays, and CSV.

# data/books.yaml
- title: The Left Hand of Darkness
  author: Ursula K. Le Guin
  year: 1969
  rating: 5
- title: Piranesi
  author: Susanna Clarke
  year: 2020
  rating: 5

Cell value types

Link dicts also accept url as an alias for href, and label as an alias for text.

{filename} links

Link href values support Pelican's {filename} syntax to cross-reference other articles:

- title: My Post
  link: {href: "{filename}posts/my-post.md", text: "Read more"}

Settings

TABULAR_COUNT_TEMPLATE and TABULAR_GROUP_COUNT_TEMPLATE have built-in defaults for zh ({n} 筆資料 / {n} 筆) and ja ({n} 件), derived from Pelican's DEFAULT_LANG setting.

Grouping

group_by reorders rows so that rows sharing the same key values are contiguous. group_summary_at adds a collapsible header row above each group that shows the group value and a row count.

{% table data/books.yaml group_by="genre,author" group_summary_at="genre" %}

This renders a genre-level header row for each genre, with all books listed beneath it. The header is collapsible via pelican-osm's osm-map.js — see CSS / JS below.

Derived group keys

A group_by (and group_summary_at) field may use a field:transform form to group by a value derived from the field rather than its raw value. The only transform currently supported is year, which extracts the year from a date/datetime:

{% table data/talks.yaml sort_by="date" sort_order="desc" group_by="date:year" group_summary_at="date:year" %}

This groups rows under a collapsible header per year while keeping the original date column intact. Sorting still operates on the underlying date.

Aggregation

When aggregate is set, rows sharing a group_by key are collapsed into a single row. Currently supported operations:

sum/avg/min/max coerce numeric-looking strings (e.g. "8.5") but skip anything that can't be parsed as a number; if no value in the group is numeric, the aggregated cell is empty.

{% table data/books.yaml group_by="author" aggregate="year:year" %}
{% table data/books.yaml group_by="genre" aggregate="rating:avg,pages:sum" %}

Column anchors

Every <th> element has an id attribute derived from the column label (e.g., id="osm-col--title"). These can be used as fragment links within the page. IDs are unique within a table; duplicate slugs get a numeric suffix (-2, -3, …).

CSS / JS

The generated HTML uses the same class names as pelican-osm (osm-place-list, osm-group-*) so the two plugins share CSS and the osm-map.js interactive sorting and group-toggle behaviour.