Markdown Table Sorter

Markdown Table Sorter is a GitHub Action that automatically sorts Markdown tables alphabetically or by a selected column.

It is useful for repositories that maintain tables in README files, documentation pages, awesome lists, glossaries, indexes, comparison tables, changelogs, or curated resource lists.

What It Does

Markdown Table Sorter scans Markdown files, detects standard pipe tables, and sorts table rows while preserving the header and alignment row.

It can sort by:

• The first column by default
• A specific 1-based column number
• An exact column header name
• The full row text using alphabetic mode

Usage

Create a workflow file such as .github/workflows/markdown-table-sorter.yml:

name: Markdown Table Sorter

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  sort-tables:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sort Markdown tables
        uses: brandonhimpfen/markdown-table-sorter@v1
        with:
          files: '**/*.md'
          column: '1'
          order: asc

Commit Changes Automatically

To sort tables and commit the changes back to the branch, combine this action with a commit step:

name: Sort Markdown Tables

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: write

jobs:
  sort-tables:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sort Markdown tables
        uses: brandonhimpfen/markdown-table-sorter@v1
        with:
          files: '**/*.md'
          column: Name
          order: asc

      - name: Commit sorted tables
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: Sort Markdown tables

Check Mode

Use check mode when you want the workflow to fail if Markdown tables are not already sorted.

- name: Check Markdown table sorting
  uses: brandonhimpfen/markdown-table-sorter@v1
  with:
    files: '**/*.md'
    column: Name
    check: 'true'

Sorting by Column Number

Column numbers are 1-based.

- name: Sort by second column
  uses: brandonhimpfen/markdown-table-sorter@v1
  with:
    files: 'docs/**/*.md'
    column: '2'

Sorting by Header Name

The column input can also use an exact header name.

- name: Sort by project name
  uses: brandonhimpfen/markdown-table-sorter@v1
  with:
    files: 'README.md'
    column: Project

Alphabetic Row Sorting

Alphabetic mode sorts by the full body row text instead of a single column.

- name: Sort rows alphabetically
  uses: brandonhimpfen/markdown-table-sorter@v1
  with:
    files: '**/*.md'
    mode: alphabetic

Inputs

Input	Description	Required	Default
files	Glob pattern for Markdown files to scan. Multiple patterns can be separated with commas.	No	**/*.md
column	Column to sort by. Use a 1-based column number or an exact header name.	No	1
order	Sort order. Supported values are asc and desc.	No	asc
mode	Sort mode. Supported values are column and alphabetic.	No	column
case-sensitive	Whether sorting should be case-sensitive.	No	false
check	If true, fail when files contain unsorted tables instead of modifying them.	No	false
min-rows	Minimum number of body rows required before a table is sorted.	No	2

Outputs

Output	Description
changed-files	Number of files changed or that would need changes in check mode.
changed-tables	Number of tables changed or that would need changes in check mode.

Supported Table Format

The action supports standard Markdown pipe tables:

| Name | Type | Status |
| --- | --- | --- |
| Zebra | Animal | Active |
| Apple | Fruit | Active |
| Maple | Tree | Active |

After sorting by the first column:

| Name | Type | Status |
| --- | --- | --- |
| Apple | Fruit | Active |
| Maple | Tree | Active |
| Zebra | Animal | Active |

Notes

Markdown Table Sorter preserves the table header and alignment row. It sorts only the body rows.

The action ignores common generated or dependency directories such as .git, node_modules, .venv, venv, dist, and build.

License

Markdown Table Sorter is released under the MIT License.