Update README for formatting and linter configuration
Add detailed instructions for configuring formatters and linters, including executable resolution order and project-specific overrides.
This commit is contained in:
parent
a0926e273e
commit
9679e2b562
|
|
@ -201,6 +201,7 @@ Was caused by settings loading at wrong time; fixed by using `LspAttach` autocmd
|
|||
- After any config or plugin change, immediately update `MIGRATION_PLAN.md` (check off items, add notes, or adjust next steps).
|
||||
- After any change or decision, also update `LOG.md:1` (decisions log and design docs).
|
||||
- **After adding/removing/editing any keymaps**, immediately update `README.md` with the change (add new entries, remove deleted mappings, or update descriptions).
|
||||
- **After changing formatter/linter configuration, standards, or tool resolution**, immediately update the "Configuration" section in `README.md` (update tool lists, override instructions, or behavior descriptions).
|
||||
- At the start of each phase, confirm scope and priorities for that phase.
|
||||
- Execute phases via subphases (`N.x`), where each bullet under a phase is its own implement-and-test step (e.g., Phase 3.1, 3.2, 3.3, 3.4).
|
||||
- Record decisions and rationale in `LOG.md:1` as they're made.
|
||||
|
|
|
|||
95
README.md
95
README.md
|
|
@ -304,3 +304,98 @@ Buffer-local keymaps available when inside a git repository:
|
|||
| Mode | Key | Description |
|
||||
| --- | --- | --- |
|
||||
| insert | `<M-e>` | Fast wrap the previous text with a pair |
|
||||
|
||||
## Configuration
|
||||
|
||||
### Formatting & Linting
|
||||
|
||||
This config uses **none-ls** for formatting and **nvim-lint** for diagnostics. Both prefer project-local tools over global installations.
|
||||
|
||||
#### Executable Resolution Order
|
||||
|
||||
When looking for formatters/linters, the config searches in this priority:
|
||||
|
||||
1. **Project-local** (e.g., `node_modules/.bin/`, `vendor/bin/`)
|
||||
2. **Mason-managed** (`~/.local/share/nvim/mason/bin/`)
|
||||
3. **System PATH** (globally installed tools)
|
||||
|
||||
See `find_executable()` helper in `lua/plugins/none-ls.lua` and `lua/plugins/nvim-lint.lua`.
|
||||
|
||||
#### Configured Tools
|
||||
|
||||
**Formatters** (`lua/plugins/none-ls.lua`):
|
||||
- **JavaScript/TypeScript/CSS/JSON/HTML/Markdown**: `prettier`
|
||||
- **PHP**: `phpcbf` (WordPress standard by default)
|
||||
- **Lua**: `stylua`
|
||||
- **Python**: handled by `ruff` LSP (not none-ls)
|
||||
|
||||
**Linters** (`lua/plugins/nvim-lint.lua`):
|
||||
- **JavaScript/TypeScript**: `eslint_d`
|
||||
- **PHP**: `phpcs` (WordPress standard by default)
|
||||
- **Markdown**: `markdownlint` (disabled by default; use `:MarkdownLintEnable`)
|
||||
- **Python**: handled by `ruff` LSP (not nvim-lint)
|
||||
|
||||
#### Project-Specific Overrides
|
||||
|
||||
Both formatters and linters respect project-level configuration files:
|
||||
|
||||
**PHP** (phpcbf + phpcs):
|
||||
- Create `phpcs.xml` or `phpcs.xml.dist` in your project root
|
||||
- When present, this file controls the coding standard (e.g., PSR-12, WordPress, custom)
|
||||
- When absent, defaults to `--standard=WordPress`
|
||||
|
||||
Example `phpcs.xml`:
|
||||
```xml
|
||||
<?xml version="1.0"?>
|
||||
<ruleset name="Custom">
|
||||
<description>Project-specific PHP rules</description>
|
||||
<rule ref="PSR12"/>
|
||||
<!-- or: <rule ref="WordPress-Core"/> -->
|
||||
|
||||
<!-- Customize rules -->
|
||||
<rule ref="Generic.Files.LineLength">
|
||||
<properties>
|
||||
<property name="lineLimit" value="120"/>
|
||||
</properties>
|
||||
</rule>
|
||||
</ruleset>
|
||||
```
|
||||
|
||||
**JavaScript/TypeScript** (prettier + eslint):
|
||||
- Project config files: `.prettierrc`, `.eslintrc.json`, `eslint.config.js`, etc.
|
||||
- Global fallback: `~/.eslintrc.json` (when no project config exists)
|
||||
|
||||
**Lua** (stylua):
|
||||
- Project config: `stylua.toml` or `.stylua.toml`
|
||||
- Falls back to stylua defaults if not present
|
||||
|
||||
**Markdown** (markdownlint):
|
||||
- Project config: `.markdownlint.json`, `.markdownlintrc`
|
||||
|
||||
#### Changing Standards Per-Project
|
||||
|
||||
To switch a PHP project from WordPress to PSR-12:
|
||||
|
||||
1. Create `phpcs.xml` in project root:
|
||||
```xml
|
||||
<?xml version="1.0"?>
|
||||
<ruleset name="PSR-12">
|
||||
<rule ref="PSR12"/>
|
||||
</ruleset>
|
||||
```
|
||||
|
||||
2. Restart Neovim (or reload config: `:source $MYVIMRC`)
|
||||
|
||||
Both `phpcs` and `phpcbf` will now use PSR-12 rules in that project.
|
||||
|
||||
#### Format-on-Save
|
||||
|
||||
- **Enabled by default** for all supported filetypes
|
||||
- **Toggle**: `<leader>lt` (see keymaps below)
|
||||
- **Manual format**: `<leader>lf` (buffer or visual selection)
|
||||
|
||||
#### Linting Behavior
|
||||
|
||||
- **Automatic**: Runs on `BufEnter`, `BufWritePost`, `InsertLeave`
|
||||
- **Per-filetype**: Configured in `lint.linters_by_ft` table
|
||||
- **Markdown**: Opt-in only (`:MarkdownLintEnable` / `:MarkdownLintDisable`)
|
||||
Loading…
Reference in New Issue