diff --git a/README.md b/README.md index 4e813c0..c6910cd 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,56 @@ # Markdown Padding -[![npm version](https://img.shields.io/npm/v/md-padding.svg)](https://www.npmjs.org/package/md-padding) -[![downloads](https://img.shields.io/npm/dm/md-padding.svg)](https://www.npmjs.org/package/md-padding) -[![Check](https://github.com/harttle/md-padding/actions/workflows/check.yml/badge.svg)](https://github.com/harttle/md-padding/actions/workflows/check.yml) -[![Release](https://github.com/harttle/md-padding/actions/workflows/release.yml/badge.svg)](https://github.com/harttle/md-padding/actions/workflows/release.yml) -[![Coveralls](https://img.shields.io/coveralls/harttle/md-padding.svg)](https://coveralls.io/github/harttle/md-padding?branch=master) -[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/harttle/md-padding) -[![GitHub issues](https://img.shields.io/github/issues-closed/harttle/md-padding.svg)](https://github.com/harttle/md-padding/issues) -[![DUB license](https://img.shields.io/dub/l/vibe-d.svg)](https://github.com/harttle/md-padding/blob/master/LICENSE) -[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits) -**排版中只有空格不能忍**，修复你 Markdown 中缺少的空格： +[![npm version](https://img.shields.io/npm/v/md-padding.svg)](https://www.npmjs.org/package/md-padding) +[![downloads](https://img.shields.io/npm/dm/md-padding.svg)](https://www.npmjs.org/package/md-padding) +[![Check](https://github.com/harttle/md-padding/actions/workflows/check.yml/badge.svg)](https://github.com/harttle/md-padding/actions/workflows/check.yml) +[![Release](https://github.com/harttle/md-padding/actions/workflows/release.yml/badge.svg)](https://github.com/harttle/md-padding/actions/workflows/release.yml) +[![Coveralls](https://img.shields.io/coveralls/harttle/md-padding.svg)](https://coveralls.io/github/harttle/md-padding?branch=master) +[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/harttle/md-padding) +[![GitHub issues](https://img.shields.io/github/issues-closed/harttle/md-padding.svg)](https://github.com/harttle/md-padding/issues) +[![DUB license](https://img.shields.io/dub/l/vibe-d.svg)](https://github.com/harttle/md-padding/blob/master/LICENSE) +[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits) -* 中英文混排时，*中文* 与 *英文* 之间，*中文* 与 *数字* 之间添加空格。 -* *特定英文标点* 后面添加空格，但 *全角标点* 前后不加空格。 -* 文字和 *行内代码* 之间、文字与 *链接* 之间、文字与 *加粗*、*强调*、*删除线* 之间添加空格。 -* 会解析生成 Markdown + 自然语言构成的 AST，最大限度解决问题同时避免误处理。 +[中文](https://github.com/harttle/md-padding/blob/master/README.zh.md) -[这里](https://github.com/harttle/md-padding/tree/master/demo) 有个例子： +**A tool for formatting Markdown content with padding** -![raw.md 和 formated.md 之间的 Diff](https://user-images.githubusercontent.com/4427974/73588871-6e8d5600-4509-11ea-8c42-9debaaad9008.png) +- *Ensures consistent spacing* before and after Markdown elements like *headings*, *lists*, and *code blocks*. +- *Aligns tables* by formatting column spacing properly. +- Supports formatting inside *code blocks* and recognizes *mathematical expressions*, *HTML elements*, *YAML front matter*, and *fenced code blocks* for correct formatting. +- Applies an extended AST parsing to ensure natural language structures like punctuations and latin characters are padded correctly. -## 使用说明 -### 在命令行使用 +Here's a [demo](https://github.com/harttle/md-padding/tree/master/demo) showing changes made by formatting: -可以 `npm i -g md-padding` 后使用，也可以用 `npx md-padding`： +![raw.md vs formatted.md - Diff](https://user-images.githubusercontent.com/4427974/73588871-6e8d5600-4509-11ea-8c42-9debaaad9008.png) + +## Command Line Interface + +Install globally via `npm`: ```bash -# 输出 README.md 格式化后的内容 +npm i -g md-padding +``` + +Or run directly using `npx`: + +```bash +# Format README.md in place npx md-padding README.md ``` -还可以接受标准输入（用在管道中），也可以原址（in-place）更改文件。详见 `md-padding --help`。 +For more options: -```none +```bash > npx md-padding --help md-padding [OPTION]... Options: --help, -h Show help [boolean] --version Show version number [boolean] - --in-place, -i edit file in place [boolean] - --ignore-words, -I ignore padding within/before/after these words [string] - --ignore-patterns, -P ignore by a list of regexp [string] - --read-files, -r read a file list containing one file per line, use empty value to read from STDIN [string] + --in-place, -i Edit file in place [boolean] + --ignore-words, -I Ignore padding for specific words [string] + --ignore-patterns, -P Ignore specific patterns using regex [string] + --read-files, -r Read file list from input, one file per line [string] Examples: stdout md-padding README.md @@ -54,57 +62,42 @@ Examples: equivalent w/ md-padding -r list.txt -i ``` -### 在 Vim 中使用 +## Vim Integration -可以绑定一个快捷键 `F6` 来修复当前文件： +Map the `F6` key to format Markdown files: ```vim -" 绑一个 Vim Filter +" Hotkey for md-padding format noremap :%!npx md-padding ``` -### 在 VS Code 中使用 - -从 Marketplace 安装 [Markdown Padding](https://marketplace.visualstudio.com/items?itemName=harttle.md-padding-vscode)。 -打开一个 Markdown 文件后，支持这些操作： - -- Command。打开 *命令面板*，输入 Markdown Padding 并回车。*命令面板* 快捷键： - - Windows：Ctrl + Shift + P - - Mac：Command + Shift + P - - Linux：Ctrl + Shift + P -- Formatting。在编辑器里右键点格式化，或者： - - Windows：Shift + Alt + F - - Mac：Shift + Option + F - - Linux：Ctrl + Shift + I +## VS Code Integration -参数 | 类型 | 描述 ---- | --- | --- -`mdpadding.ignoreWords` | `Array` | 这些字词内部和前后禁止加空格 -`mdpadding.ignorePatterns` | `Array` | 这些正则内部和前后禁止加空格 +Install the [Markdown Padding](https://marketplace.visualstudio.com/items?itemName=harttle.md-padding-vscode) extension. -## 功能说明 +- Open Command Palette (`Ctrl + Shift + P` on Windows/Linux, `Cmd + Shift + P` on macOS) and run `Markdown Padding`. +- Use the default formatting shortcut: + - `Shift + Alt + F` (Windows) + - `Shift + Option + F` (Mac) + - `Ctrl + Shift + I` (Linux) -### 中英混排 -中英混排的正文内容，会确保中英之间的空格。 +### Configuration -### 标点符号 -需要空格的标点（比如半角逗号），会在适当的位置追加空格。 +| Setting | Type | Description | +| -------------------------- | --------------- | ----------------------------------------------- | +| `mdpadding.ignoreWords` | `Array` | Words to exclude from padding adjustments | +| `mdpadding.ignorePatterns` | `Array` | Regular expressions defining patterns to ignore | -### 代码注释 -代码格式化不是本仓库的功能之一，请使用对应语言的 prettifier。但代码中的注释会被当做 Markdown 正文来格式化，目前支持这些语言的注释： +## Q & A -- cpp, c, java, javascript, typescript, csharp, go -- sql -- bash, python, ruby +### How to ignore a specific section -### 忽略片段 +You can exclude certain sections from formatting using the `md-padding-ignore` directive: -有些片段希望保持原状，这时可以用 `md-padding-ignore` 来包裹起来。 - ```markdown -下面是一段不需要格式化的文本 +Some text before the ignored section. -a*b=c, b>1 => a1 => a<c -现在开始又可以格式化了。 +This text will be formatted as usual. ``` diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 0000000..a3bfff1 --- /dev/null +++ b/README.zh.md @@ -0,0 +1,110 @@ +# Markdown Padding +[![npm version](https://img.shields.io/npm/v/md-padding.svg)](https://www.npmjs.org/package/md-padding) +[![downloads](https://img.shields.io/npm/dm/md-padding.svg)](https://www.npmjs.org/package/md-padding) +[![Check](https://github.com/harttle/md-padding/actions/workflows/check.yml/badge.svg)](https://github.com/harttle/md-padding/actions/workflows/check.yml) +[![Release](https://github.com/harttle/md-padding/actions/workflows/release.yml/badge.svg)](https://github.com/harttle/md-padding/actions/workflows/release.yml) +[![Coveralls](https://img.shields.io/coveralls/harttle/md-padding.svg)](https://coveralls.io/github/harttle/md-padding?branch=master) +[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/harttle/md-padding) +[![GitHub issues](https://img.shields.io/github/issues-closed/harttle/md-padding.svg)](https://github.com/harttle/md-padding/issues) +[![DUB license](https://img.shields.io/dub/l/vibe-d.svg)](https://github.com/harttle/md-padding/blob/master/LICENSE) +[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits) + +**排版中只有空格不能忍**，修复你 Markdown 中缺少的空格： + +* 中英文混排时，*中文* 与 *英文* 之间，*中文* 与 *数字* 之间添加空格。 +* *特定英文标点* 后面添加空格，但 *全角标点* 前后不加空格。 +* 文字和 *行内代码* 之间、文字与 *链接* 之间、文字与 *加粗*、*强调*、*删除线* 之间添加空格。 +* 会解析生成 Markdown + 自然语言构成的 AST，最大限度解决问题同时避免误处理。 + +[这里](https://github.com/harttle/md-padding/tree/master/demo) 有个例子： + +![raw.md 和 formated.md 之间的 Diff](https://user-images.githubusercontent.com/4427974/73588871-6e8d5600-4509-11ea-8c42-9debaaad9008.png) + +## 使用说明 +### 在命令行使用 + +可以 `npm i -g md-padding` 后使用，也可以用 `npx md-padding`： + +```bash +# 输出 README.md 格式化后的内容 +npx md-padding README.md +``` + +还可以接受标准输入（用在管道中），也可以原址（in-place）更改文件。详见 `md-padding --help`。 + +```none +> npx md-padding --help +md-padding [OPTION]... + +Options: + --help, -h Show help [boolean] + --version Show version number [boolean] + --in-place, -i Edit file in place [boolean] + --ignore-words, -I Ignore padding within/before/after these words [string] + --ignore-patterns, -P Ignore by a list of regexp [string] + --read-files, -r Read a file list containing one file per line, use empty value to read from STDIN [string] + +Examples: + stdout md-padding README.md + in-place md-padding -i README.md + pipe cat README.md | md-padding + ignore-words cat README.md | md-padding -I '=' '::' + ignore-patterns cat README.md | md-padding -P '=' ':+' + batch format cat list.txt | md-padding -r -i + equivalent w/ md-padding -r list.txt -i +``` + +### 在 Vim 中使用 + +可以绑定一个快捷键 `F6` 来修复当前文件： + +```vim +" 绑一个 Vim Filter +noremap :%!npx md-padding +``` + +### 在 VS Code 中使用 + +从 Marketplace 安装 [Markdown Padding](https://marketplace.visualstudio.com/items?itemName=harttle.md-padding-vscode)。 +打开一个 Markdown 文件后，支持这些操作： + +- Command。打开 *命令面板*，输入 Markdown Padding 并回车。*命令面板* 快捷键： + - Windows：Ctrl + Shift + P + - Mac：Command + Shift + P + - Linux：Ctrl + Shift + P +- Formatting。在编辑器里右键点格式化，或者： + - Windows：Shift + Alt + F + - Mac：Shift + Option + F + - Linux：Ctrl + Shift + I + +参数 | 类型 | 描述 +--- | --- | --- +`mdpadding.ignoreWords` | `Array` | 这些字词内部和前后禁止加空格 +`mdpadding.ignorePatterns` | `Array` | 这些正则内部和前后禁止加空格 + +## 功能说明 + +### 中英混排 +中英混排的正文内容，会确保中英之间的空格。 + +### 标点符号 +需要空格的标点（比如半角逗号），会在适当的位置追加空格。 + +### 代码注释 +代码格式化不是本仓库的功能之一，请使用对应语言的 prettifier。但代码中的注释会被当做 Markdown 正文来格式化，目前支持这些语言的注释： + +- cpp, c, java, javascript, typescript, csharp, go +- sql +- bash, python, ruby + +### 忽略片段 + +有些片段希望保持原状，这时可以用 `md-padding-ignore` 来包裹起来。 + +```markdown +下面是一段不需要格式化的文本 + +a*b=c, b>1 => a +现在开始又可以格式化了。 +``` diff --git a/src/bin/md-padding.ts b/src/bin/md-padding.ts index b08a6e8..f9452e4 100755 --- a/src/bin/md-padding.ts +++ b/src/bin/md-padding.ts @@ -10,30 +10,30 @@ yargs .option('in-place', { alias: 'i', type: 'boolean', - description: 'edit file in place' + description: 'Edit file in place' }) .option('ignore-words', { alias: 'I', type: 'array', - description: 'ignore padding within/before/after these words', + description: 'Ignore padding within/before/after these words', coerce: (arr) => arr.map((item: any) => String(item)) }) .option('ignore-patterns', { alias: 'I', type: 'array', - description: 'ignore by a list of regexp', + description: 'Ignore by a list of regexp', coerce: (arr) => arr.map((item: any) => String(item)) }) .option('file', { alias: 'f', type: 'array', - description: 'to specify file list, used with -I', + description: 'To specify file list, used with -I', coerce: (arr) => arr.map((item: any) => String(item)) }) .option('read-files', { alias: 'r', type: 'string', - description: 'read a file list containing one file per line, use empty value to read from STDIN' + description: 'Read a file list containing one file per line, use empty value to read from STDIN' }) .alias('help', 'h') .example('stdout', 'mdp README.md')