ml-md-table
Format Markdown tables with markdown-table and align cells by character display width, so tables mixing CJK (Chinese / Japanese / Korean) and Latin text stay lined up.
使用 markdown-table 格式化 Markdown 表格，并按字符显示宽度对齐单元格，解决全角和半角字符混排时 | 对不齐的问题。
Features | 功能
- Aligns mixed CJK / Latin cells by display width instead of string length.
按字符显示宽度对齐中英文混排单元格，而不是按字符个数。
- The full-width / half-width ratio is configurable, decimals supported (
mdTable.cjkWidth).
全角/半角的换算比例可配置，支持小数（mdTable.cjkWidth）。
- Can be turned off entirely: with width calculation disabled every cell keeps exactly one space around it, i.e.
| cell | cell | (mdTable.widthAware).
可以直接关闭宽度计算：关闭后所有单元格与竖线之间只留一个空格，即 | 单元格 | 单元格 |（mdTable.widthAware）。
- Keeps column alignment markers (
:---, :---:, ---:), normalizes blank cells and pads missing columns.
保留列对齐标记（:---、:---:、---:），清理多余空格、补齐缺失的列。
- Skips tables inside fenced code blocks and lines that only look like a table.
跳过围栏代码块内的表格，以及只是含有竖线的普通段落。
- Optional formatting on save (
mdTable.formatOnSave).
可选保存时自动格式化（mdTable.formatOnSave）。
Commands | 命令
| Command |
命令 |
Description |
说明 |
ml_md_table.format |
格式化当前表格 |
Format the table the cursor is in. |
格式化光标所在的那张表。 |
ml_md_table.formatAll |
格式化文档中所有表格 |
Format every table in the document. |
格式化文档中所有表格。 |
Usage | 使用方法
- Command Palette:
Ctrl+Shift+P (Cmd+Shift+P on macOS) → type Format Current MD Table or Format All MD Tables.
命令面板：Ctrl+Shift+P（macOS 为 Cmd+Shift+P）→ 输入 Format Current MD Table 或 Format All MD Tables。
- Format on save: on by default (
mdTable.formatOnSave), every save of a Markdown file formats all its tables.
保存时自动格式化：默认开启（mdTable.formatOnSave），每次保存 Markdown 文件都会格式化其中所有表格。
Both commands only work on markdown documents.
两个命令只对 markdown 文档生效。
Settings | 配置
| Setting |
Type |
Default |
Description |
说明 |
mdTable.widthAware |
boolean |
true |
Align by display width. When false, no width is calculated and every cell keeps one space next to each pipe. |
是否按显示宽度对齐。为 false 时不计算宽度，所有单元格与竖线之间只留一个空格。 |
mdTable.cjkWidth |
number |
2 |
How many half-width characters wide one full-width character is. Decimals allowed. |
一个全角字符相当于多少个半角字符宽度，支持小数。 |
mdTable.formatOnSave |
boolean |
true |
Format all tables in a Markdown file when it is saved. |
保存 Markdown 文件时自动格式化所有表格。 |
Settings live under the ml-md-table section in the Settings UI, or in settings.json:
配置项位于设置界面的 ml-md-table 分组，也可以直接写进 settings.json：
{
"mdTable.widthAware": true,
"mdTable.cjkWidth": 1.667,
"mdTable.formatOnSave": true
}
How the alignment works | 对齐原理
A monospaced font gives a CJK character a different width from a Latin one, while Markdown tables can only be padded with spaces. Two things follow:
等宽字体下汉字与英文字母的宽度不同，而 Markdown 表格只能用空格填充，于是有两点：
mdTable.cjkWidth should match the font you actually use. A CJK character is not always exactly 2 half-widths wide — most programming fonts (JetBrains Mono, Fira Code, Cascadia Code) are about 1.667, Consolas about 1.818. Starting from the default 2 and lowering it usually removes the visible drift.
mdTable.cjkWidth 要贴近你实际使用的字体。汉字并不总是正好 2 个半角宽——多数编程字体（JetBrains Mono、Fira Code、Cascadia Code）约 1.667，Consolas 约 1.818。从默认值 2 往下调，通常就能消掉肉眼可见的错位。- Perfect alignment is not always achievable. Cell widths are rounded to whole columns before padding, so each column may carry up to half a column of residual error, and the offsets accumulate across columns — expect up to about one column of drift on wide tables. If you would rather have a stable, width-independent layout, set
mdTable.widthAware to false.
完美对齐并非总能做到。列宽在补空格前会被取整到整列，因此每列最多残留半列误差，且会沿列累积——列数较多时最多约一列偏差。如果更想要与宽度无关的稳定版式，把 mdTable.widthAware 设为 false。
Characters whose width is ambiguous in CJK fonts (—, ·, ×, etc.) are counted as one half-width by the width library but may render wider, which also shows up as a constant offset.
在中文语境下宽度有歧义的字符（—、·、× 等）会被宽度库算作一个半角，但实际渲染可能更宽，同样表现为固定错位。
Example | 示例
Before formatting (misaligned) / 格式化前（错位）：
| 姓名 | 语言 | 说明 |
| ----- | :-----: | ---------------------: |
| 张三 | 中文 | 这是一个很长的中文描述 |
| Alice | English | short |
After formatting with mdTable.cjkWidth: 1.667 / 用 mdTable.cjkWidth: 1.667 格式化后：
| 姓名 | 语言 | 说明 |
| ----- | :-----: | ---------------------: |
| 张三 | 中文 | 这是一个很长的中文描述 |
| Alice | English | short |
Development | 开发
npm install
npm run compile # bundle src/ to dist/extension.js / 打包到 dist/
npm run watch # rebuild on change / 改动即重新打包
npm test # core + extension integration tests / 核心逻辑与扩展链路测试
npm run package # produce .vsix / 生成 .vsix
To try it locally: run npm run package, then in the editor use Extensions: Install from VSIX..., or copy the unpacked folder (package.json + dist/) into <user data>/extensions/ and reload the window.
本地试用：执行 npm run package，然后在编辑器中用 扩展：从 VSIX 安装…；或把解压后的目录（package.json + dist/）拷进 <用户数据目录>/extensions/，再重载窗口。
