74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
|
---
|
||
|
|
description: Revisa y corrige avisos comunes de markdownlint en ficheros .md del repo (raíz, .claude, .agents, packages...). No hay devDep ni CI; el repaso es manual y se invoca a demanda.
|
||
|
|
---
|
||
|
|
|
||
|
|
# /md-lint — limpieza de markdown
|
||
|
|
|
||
|
|
Aplica un repaso de estilo a los `.md` del repo según las reglas que más se cuelan en este proyecto. No hay `markdownlint-cli2` instalado y no se quiere añadir como devDep — el barrido es manual contra el set de reglas de abajo.
|
||
|
|
|
||
|
|
## Argumento
|
||
|
|
|
||
|
|
`$ARGUMENTS` opcional. Si está, acota el barrido a esa ruta (fichero concreto, carpeta, glob). Si no, barre todo el repo excluyendo:
|
||
|
|
|
||
|
|
- `node_modules/`
|
||
|
|
- `dist/`
|
||
|
|
- `.git/`
|
||
|
|
- `coverage/`
|
||
|
|
|
||
|
|
Para listar candidatos:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
find . -name "*.md" -not -path "./node_modules/*" -not -path "./dist/*" -not -path "./.git/*" -not -path "*/coverage/*"
|
||
|
|
```
|
||
|
|
|
||
|
|
## Reglas que se revisan
|
||
|
|
|
||
|
|
Set mínimo, alineado con lo que el editor del usuario marca y con el estilo ya presente en `README.md` y `CLAUDE.md`:
|
||
|
|
|
||
|
|
- **MD004 — list-style:** listas con `-`, no con `*`.
|
||
|
|
- **MD030 — list-marker-space:** un único espacio tras `-` o `1.` (no `* ` ni `1. `).
|
||
|
|
- **MD032 — blanks-around-lists:** una línea en blanco antes y después de cada lista.
|
||
|
|
- **MD031 — blanks-around-fences:** una línea en blanco antes y después de cada bloque ` ``` `.
|
||
|
|
- **MD036 — no-emphasis-as-heading:** `**Sección:**` en línea propia → heading real (`####`). Si la línea es la firma del documento o contenido decorativo (no es un encabezado lógico), convertir a texto plano en vez de inventar un heading.
|
||
|
|
- **MD040 — fenced-code-language:** todo bloque ` ``` ` debe declarar lenguaje (`text`, `bash`, `ts`, `json`...).
|
||
|
|
- **MD026 — no-trailing-punctuation-in-heading:** headings sin `:` ni `.` al final.
|
||
|
|
- **MD047 — single-trailing-newline:** el fichero termina con un único `\n` final.
|
||
|
|
- **MD034 — no-bare-urls:** URLs en texto deben ir en `<...>` o como link `[texto](url)`.
|
||
|
|
|
||
|
|
No se tocan:
|
||
|
|
|
||
|
|
- Contenido (typos, gramática, redacción) — solo formato. Excepción: si encuentras un typo obvio en un encabezado o una frase muy corta, repórtalo al final pero no lo arregles sin permiso.
|
||
|
|
- Longitud de línea (MD013): el repo no la fuerza.
|
||
|
|
- Estilo de heading ATX vs Setext: ya está unificado en ATX (`#`).
|
||
|
|
|
||
|
|
## Cómo proceder
|
||
|
|
|
||
|
|
1. Resuelve la lista de ficheros (`$ARGUMENTS` o barrido completo).
|
||
|
|
2. Si son más de ~5 ficheros, despacha el trabajo a subagentes en paralelo agrupando por carpeta (ver skill `dispatching-parallel-agents`). Cada subagente recibe un grupo y este mismo set de reglas.
|
||
|
|
3. Para cada fichero, lee y aplica las reglas con `Edit`. No reescribas el fichero entero con `Write` salvo que el delta sea masivo.
|
||
|
|
4. No introduzcas cambios fuera del set de reglas. No reordenes secciones, no añadas contenido.
|
||
|
|
|
||
|
|
## Formato de reporte
|
||
|
|
|
||
|
|
Tabla resumen al terminar:
|
||
|
|
|
||
|
|
```text
|
||
|
|
fichero cambios
|
||
|
|
----------------------------- -------
|
||
|
|
CONTRIBUTING.md 12 (MD004, MD030, MD036, typo)
|
||
|
|
.claude/rules/code-style.md 0
|
||
|
|
.agents/skills/.../HOUSE.md 3 (MD031, MD040)
|
||
|
|
```
|
||
|
|
|
||
|
|
Si encontraste typos o problemas de contenido que no arreglaste (por estar fuera de scope), lístalos en una sección **Sugerencias** al final para que el usuario decida.
|
||
|
|
|
||
|
|
## Cuándo invocarlo
|
||
|
|
|
||
|
|
Es opcional, no hay CI que lo ejecute. Casos típicos:
|
||
|
|
|
||
|
|
- Tras editar varios `.md` seguidos y que el editor empiece a marcar avisos.
|
||
|
|
- Antes de un PR que toca documentación.
|
||
|
|
- Limpieza periódica si el repo arrastra inconsistencias.
|
||
|
|
|
||
|
|
No lo invoques de oficio.
|