MkDocs XTables

MkDocs XTables extends standard Markdown tables after MkDocs renders them as HTML. It adds cell merging, theme-aware colors, named styles, dimensions and alignment, responsive scrolling, sticky headers/columns, touch interaction, and accessible sorting while keeping the Markdown source readable.

• Documentation and live examples: https://rod2ik.gitlab.io/mkdocs-xtables/
• Source: https://gitlab.com/rod2ik/mkdocs-xtables
• npm: @rod2ik/mkdocs-xtables

Quick example

| > | Student | {@orange} Score | City |
|---|---------|-----------------|------|
| {@blue} Alice | Mathematics | 15 | Marseille |
| ^ | Computer science | 18 {cell="@success"} | ^ |
{ .xtable sortable sticky-header sticky-cols="1" caption="Results" }

> merges horizontally into the content cell on its right. ^ extends the compatible content cell above. A metadata line immediately after the table activates table-level options.

Installation

The simplest MkDocs integration uses the classic loader; it imports the ES module and matching stylesheet automatically:

extra_javascript:
  - javascripts/xtables.config.js
  - https://cdn.jsdelivr.net/npm/@rod2ik/mkdocs-xtables@latest/dist/min/mkdocs-xtables-loader.min.js

For the full installation choices, configuration model, syntax, sorting methods, API, and examples, use the documentation site.

International date sorting

XTables integrates @rod2ik/tablesort-date-i18n directly into its lazy sorting feature. The exact dependency version is pinned in package.json; users must not load Tablesort's standard date plugin or an additional date-plugin script.

Supported methods are date, date.dmy, date.mdy, and date.ymd. The automatic date method resolves through the XTables date configuration and the plugin's locale resolver.

Development

The project uses Yarn 4.17.1. A normal local validation is:

corepack enable
yarn install
yarn bfc
yarn dev

yarn dev builds XTables, synchronizes the generated documentation vendor, and serves MkDocs. When a sibling ../tablesort-date-i18n repository exists and its version matches the exact dependency pinned in package.json, development automatically uses that local build. GitLab CI has no sibling checkout and therefore uses the pinned npm dependency.

The canonical development documentation is under Development on the MkDocs site. It documents every Yarn command, the incremental vendor mechanism, local-vs-CI dependency resolution, validation, and releases.

Versioning and releases

package.json is the single source of truth for the XTables version. After changing only its version field and updating CHANGELOG.md:

yarn bfc
git add .
git commit -m "Release X.Y.Z"
git push
git tag vX.Y.Z
git push origin vX.Y.Z

GitLab verifies that the tag equals v + package.json.version, publishes npm through Trusted Publishing, then creates the GitLab Release.

License

GNU GPL version 3 or later.