📊 neat-tables

Smart Markdown table formatter with emoji support and visual width calculations

Perfect alignment for AI-friendly documentation with proper handling of:

• ✨ Emoji characters
• 🌏 CJK (Chinese/Japanese/Korean) characters
• 🔤 Combining characters
• 📏 Accurate visual width calculations

🚀 Quick Start

# Use with npx (no installation needed)
npx @muid-io/neat-tables document.md

# Or install globally
npm install -g @muid-io/neat-tables
neat-tables document.md

# Short alias
ntables document.md

✨ Features

• Smart Visual Width: Accurate calculations for emoji, CJK, and combining characters
• Emoji Compensation: Configurable compensation for different font renderings
• Alignment Support: Left, center, and right alignment in tables
• Universal Table Support 🆕: Handles group headers and variable column counts
• Context-Aware Parsing 🆕: Strict validation for table start, relaxed for continuation
• Auto-Padding 🆕: Automatically fills missing columns with empty cells
• In-Place Formatting: Overwrites original file (backup recommended)
• Dry-Run Mode: Preview changes without modifying files
• Custom Output: Save formatted tables to a different file

📖 Usage

Basic Usage

# Format tables in-place (overwrites file)
neat-tables document.md

# Preview without modifying
neat-tables document.md --dry-run

# Save to different file
neat-tables document.md --output formatted.md

Emoji Compensation

Different fonts render emoji with different widths. Use compensation if your tables look misaligned:

# No compensation (emoji = 2.0 visual width)
neat-tables document.md

# Light compensation (emoji = 2.1)
neat-tables document.md --emoji-compensation 0.1

# Medium compensation (emoji = 2.2)
neat-tables document.md --emoji-compensation 0.2

Configuration File

Create .table-format.config (JSON) in your project:

{
  "emoji_compensation": 0.1
}

Then run:

neat-tables document.md --config .table-format.config

🎯 Examples

Example 1: Basic Alignment

Input (misaligned):

| Feature | Status | Description |
|---|---|---|
| 🚀 Speed | ✅ Done | Fast processing |
| 📊 Tables | 🔄 WIP | Smart alignment |

Output (perfectly aligned):

| Feature    | Status  | Description      |
|------------|---------|------------------|
| 🚀 Speed   | ✅ Done | Fast processing  |
| 📊 Tables  | 🔄 WIP  | Smart alignment  |

Example 2: Group Headers (NEW in v1.1.0) 🆕

Input (with single-column group headers):

| Field | Type | Description |
| ----- | ---- | ----------- |
| **IDENTIFICATION** |
| user_id | int | User ID |
| email | string | Email address |
| **METADATA** |
| created_at | timestamp | Creation time |

Output (auto-padded with empty cells):

| Field              | Type      | Description   |
| ------------------ | --------- | ------------- |
| **IDENTIFICATION** |           |               |
| user_id            | int       | User ID       |
| email              | string    | Email address |
| **METADATA**       |           |               |
| created_at         | timestamp | Creation time |

The tool now automatically:

• Detects group header rows with fewer columns
• Pads them with empty cells to match table width
• Maintains perfect alignment across all rows

🔧 Command-Line Options

Usage: neat-tables INPUT_FILE [OPTIONS]

Options:
  --output, -o FILE          Output to specific file (default: overwrite input)
  --dry-run, -d             Show result without writing file
  --emoji-compensation, -e  Emoji width compensation (0.0-0.5)
  --config, -c FILE         Load settings from JSON config file
  --help                    Show this help message

🧠 How It Works

Visual Width Calculation

The tool calculates accurate visual width considering:

1. ASCII characters: width = 1
2. Emoji: width = 2.0 + compensation
3. Wide characters (CJK): width = 2
4. Combining characters: width = 0
5. Zero-width characters: width = 0

Alignment Strategies

• Left align (default): content + padding
• Right align: padding + content
• Center align: left_padding + content + right_padding

Separator Detection

Recognizes standard Markdown table separators:

• |---|---|---| (left align)
• |:---|:---|:---| (left align explicit)
• |:---:|:---:|:---:| (center align)
• |---:|---:|---:| (right align)

📚 Integration with Other Tools

Use with smart-toc

Combine with @muid-io/smart-toc for complete documentation formatting:

# Generate TOC
npx @muid-io/smart-toc document.md

# Format tables
npx @muid-io/neat-tables document.md

Git Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit
npx @muid-io/neat-tables **/*.md

CI/CD Pipeline

# .github/workflows/format-tables.yml
name: Format Tables
on: [push]
jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npx @muid-io/neat-tables **/*.md

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Links

• NPM Package: https://www.npmjs.com/package/@muid-io/neat-tables
• GitHub: https://github.com/muid-io/neat-tables
• Homepage: https://muid.io
• Related Tools: @muid-io/smart-toc

👨‍💻 Author

LifeAiTools - muid.io

Generated with ❤️ by LifeAiTools for AI-friendly documentation