|
| 1 | +# format |
| 2 | + |
| 3 | +Format documentation files by fixing common issues like irregular space |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +``` |
| 8 | +docs-builder format --check [options...] |
| 9 | +docs-builder format --write [options...] |
| 10 | +``` |
| 11 | + |
| 12 | +## Options |
| 13 | + |
| 14 | +`--check` |
| 15 | +: Check if files need formatting without modifying them. Exits with code 1 if formatting is needed, 0 if all files are properly formatted. (required, mutually exclusive with --write) |
| 16 | + |
| 17 | +`--write` |
| 18 | +: Write formatting changes to files. (required, mutually exclusive with --check) |
| 19 | + |
| 20 | +`-p|--path` `<string>` |
| 21 | +: Path to the documentation folder, defaults to pwd. (optional) |
| 22 | + |
| 23 | +## Description |
| 24 | + |
| 25 | +The `format` command automatically detects and fixes formatting issues in your documentation files. The command only processes Markdown files (`.md`) that are included in your `_docset.yml` table of contents, ensuring that only intentional documentation files are modified. |
| 26 | + |
| 27 | +You must specify exactly one of `--check` or `--write`: |
| 28 | +- `--check` validates formatting without modifying files, useful for CI/CD pipelines |
| 29 | +- `--write` applies formatting changes to files |
| 30 | + |
| 31 | +Currently, it handles irregular space characters that may impair Markdown rendering. |
| 32 | + |
| 33 | +### Irregular Space Detection |
| 34 | + |
| 35 | +The format command detects and replaces 24 types of irregular space characters with regular spaces, including: |
| 36 | + |
| 37 | +- No-Break Space (U+00A0) |
| 38 | +- En Space (U+2002) |
| 39 | +- Em Space (U+2003) |
| 40 | +- Zero Width Space (U+200B) |
| 41 | +- Line Separator (U+2028) |
| 42 | +- Paragraph Separator (U+2029) |
| 43 | +- And 18 other irregular space variants |
| 44 | + |
| 45 | +These characters can cause unexpected rendering issues in Markdown and are often introduced accidentally through copy-paste operations from other applications. |
| 46 | + |
| 47 | +## Examples |
| 48 | + |
| 49 | +### Check if formatting is needed (CI/CD) |
| 50 | + |
| 51 | +```bash |
| 52 | +docs-builder format --check |
| 53 | +``` |
| 54 | + |
| 55 | +Exit codes: |
| 56 | +- `0`: All files are properly formatted |
| 57 | +- `1`: Some files need formatting |
| 58 | + |
| 59 | +### Apply formatting changes |
| 60 | + |
| 61 | +```bash |
| 62 | +docs-builder format --write |
| 63 | +``` |
| 64 | + |
| 65 | +### Check specific documentation folder |
| 66 | + |
| 67 | +```bash |
| 68 | +docs-builder format --check --path /path/to/docs |
| 69 | +``` |
| 70 | + |
| 71 | +### Format specific documentation folder |
| 72 | + |
| 73 | +```bash |
| 74 | +docs-builder format --write --path /path/to/docs |
| 75 | +``` |
| 76 | + |
| 77 | +## Output |
| 78 | + |
| 79 | +### Check mode output |
| 80 | + |
| 81 | +When using `--check`, the command reports which files need formatting: |
| 82 | + |
| 83 | +``` |
| 84 | +Checking documentation in: /path/to/docs |
| 85 | +
|
| 86 | +Formatting needed: |
| 87 | + Files needing formatting: 2 |
| 88 | + irregular space fixes needed: 3 |
| 89 | +
|
| 90 | +Run 'docs-builder format --write' to apply changes |
| 91 | +``` |
| 92 | + |
| 93 | +### Write mode output |
| 94 | + |
| 95 | +When using `--write`, the command reports the changes made: |
| 96 | + |
| 97 | +``` |
| 98 | +Formatting documentation in: /path/to/docs |
| 99 | +Formatted index.md (2 change(s)) |
| 100 | +
|
| 101 | +Formatting complete: |
| 102 | + Files processed: 155 |
| 103 | + Files modified: 1 |
| 104 | + irregular space fixes: 2 |
| 105 | +``` |
| 106 | + |
| 107 | +## Future Enhancements |
| 108 | + |
| 109 | +The format command is designed to be extended with additional formatting capabilities in the future, such as: |
| 110 | + |
| 111 | +- Line ending normalization |
| 112 | +- Trailing whitespace removal |
| 113 | +- Consistent heading spacing |
| 114 | +- And other formatting fixes |
0 commit comments