markuplint-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# markuplint-setup

Set up Markuplint in a project from scratch.

## When to Use

- "Set up markuplint" / "Add markuplint to this project"
- "I want to lint my HTML"
- "Install markuplint"

## Steps

### 1. Check Existing Installation

- Check `package.json` for `markuplint` and `@markuplint/*` packages
- Check for config files (`.markuplintrc*`, `markuplint.config.*`)
- If already installed, tell the user and suggest `/markuplint-configure` instead

### 2. Detect Project Type

Scan the project:

- **Package manager**: check for `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml`
- **Framework**: check `package.json` dependencies for `react`, `vue`, `svelte`, `astro`, `@alpinejs/csp`, etc. Also check file extensions (`.jsx`, `.tsx`, `.vue`, `.svelte`, `.astro`, `.pug`, `.php`)
- **Monorepo**: check for `workspaces` in `package.json` or `lerna.json` / `nx.json` / `turbo.json`

### 3. Choose Preset and Packages

Use `WebFetch` to get the latest supported syntaxes and preset information:

- Presets: fetch https://markuplint.dev/docs/guides/presets
- Framework parsers: fetch https://markuplint.dev/docs/guides/beyond-html

If installing a prerelease version (`alpha` / `beta` / `rc`), use `https://next.markuplint.dev` as the doc base instead — the stable site does not document prerelease behavior.

**Use AskUserQuestion to confirm:**

1. Detected framework — is it correct?
2. Which preset to use? (recommend based on framework)

### 4. Install Packages

Install using the detected package manager. Example:

```shell
npm install -D markuplint @markuplint/jsx-parser @markuplint/react-spec
```

**Do NOT use `npx markuplint --init`** — it requires interactive terminal input.

### 5. Create Configuration File

Write `.markuplintrc` directly. Keep it minimal — only include what's needed for the detected framework.

Static HTML needs no `parser` or `specs`:

```json
{
  "extends": ["markuplint:recommended"]
}
```

Framework projects need parser and spec:

```json
{
  "extends": ["markuplint:recommended-react"],
  "parser": {
    "\\.[jt]sx$": "@markuplint/jsx-parser"
  },
  "specs": {
    "\\.[jt]sx$": "@markuplint/react-spec"
  }
}
```

Refer to https://markuplint.dev/docs/guides/beyond-html for the exact parser/spec package names and file patterns for each framework.

#### When to use JavaScript/TypeScript config

If the project uses external config plugins or shared configs that require fine-grained merging, recommend `markuplint.config.ts` (or `.js`) with spread syntax — similar to ESLint's flat config pattern:

```ts
import type { Config } from '@markuplint/ml-config';
import reactConfig from '@example/markuplint-config-react';

const config: Config = {
  ...reactConfig,
  rules: {
    ...reactConfig.rules,
    'class-naming': '/^[a-z][a-z0-9-]*$/',
  },
};

export default config;
```

This gives full control over merge order and avoids the limitations of JSON `extends` (which uses a fixed merge strategy). Use JSON for simple setups; use JS/TS when composing multiple configs.

### 6. Run Initial Lint

Run Markuplint and capture the results:

```shell
npx markuplint "$ARGUMENTS" --format JSON
```

If `$ARGUMENTS` is empty, ask the user for the target glob (e.g., `"src/**/*.html"`).

Summarize:
- Total violation count
- Breakdown by rule (which rules have the most violations)
- Whether violations are concentrated in specific files/directories

### 7. Rule-by-Rule Adoption Decision

**Use AskUserQuestion for each rule that has violations.** Present rules one at a time (or batch related rules).

For each rule, explain what it checks (fetch the rule page if needed: `https://markuplint.dev/docs/rules/{rule-id}`) and offer options:

From markuplint/markuplint, MIT.

More from markuplint/markuplint