# Ignoring EkLine review rules

import { Aside, Tabs, TabItem, Steps } from '@astrojs/starlight/components';

Sometimes EkLine flags content you want to keep as-is. This guide helps you decide how to handle these situations and shows you the options available.

## Deciding how to handle an issue

When EkLine flags something, you have three options:

| Situation | Recommended action |
|-----------|-------------------|
| EkLine is right, fix the issue | Edit your content |
| False positive on specific content | Use an inline ignore comment |
| Rule doesn't apply to your project | Disable the rule in config |

<Aside type="tip">
Before ignoring, consider whether the flag is actually correct. EkLine catches real issues that are often overlooked.
</Aside>

---

## Finding the rule ID

When EkLine flags an issue in a PR comment or CLI output, the rule ID appears in brackets:

```
[EK00300] "responce" should be "response"
```

The **rule ID** (like `EK00300`) is what you use in ignore comments to target specific rules instead of ignoring everything.

---

## File format syntax

The comment syntax varies by file type. EkLine automatically detects the format.

<Tabs>
  <TabItem label="Markdown / HTML">
    ```markdown
    <!-- ekline-ignore-file -->
    <!-- ekline-ignore-start -->
    <!-- ekline-ignore-end -->
    <!-- ekline-ignore-next-line EK00001 -->
    <!-- ekline-ignore-line -->
    ```

    **File types:** `.md`, `.markdown`, `.html`, `.htm`, `.xml`, `.dita`, `.ditamap`
  </TabItem>
  <TabItem label="MDX">
    JSX comments (preferred):
    ```mdx
    {/* ekline-ignore-file */}
    {/* ekline-ignore-start */}
    {/* ekline-ignore-end */}
    {/* ekline-ignore-next-line EK00001 */}
    {/* ekline-ignore-line */}
    ```

    HTML comments also work in MDX files.

    **File types:** `.mdx`
  </TabItem>
  <TabItem label="AsciiDoc">
    ```asciidoc
    // ekline-ignore-file
    // ekline-ignore-start
    // ekline-ignore-end
    // ekline-ignore-next-line EK00001
    // ekline-ignore-line
    ```

    **File types:** `.adoc`, `.asciidoc`
  </TabItem>
</Tabs>

---

## Ignore rules globally

For rules you want to disable across your entire project, use the config file.

In `ekline.config.json`:

```json
{
  "contentDirectory": ["docs"],
  "ignore": ["EK00001", "EK00004"]
}
```

These rules won't be checked anywhere in your project.

## Ignore rules using inline comments

Use inline comments to ignore rules for specific content without affecting the rest of your documentation.

### Quick reference

| Scope | Syntax |
|-------|--------|
| Entire file | `<!-- ekline-ignore-file -->` |
| Section | `<!-- ekline-ignore-start -->` ... `<!-- ekline-ignore-end -->` |
| Next line | `<!-- ekline-ignore-next-line -->` |
| Same line | `<!-- ekline-ignore-line -->` |

Add rule IDs to target specific rules: `<!-- ekline-ignore-next-line EK00001 -->`

Add reasons to document why: `<!-- ekline-ignore-next-line EK00001 -- legacy naming -->`

### Ignoring the next line

The most common pattern. Place the comment on the line before the content you want to ignore.

```markdown
<!-- ekline-ignore-next-line -->
This line won't be checked.

This line will be checked normally.
```

**With specific rules:**
```markdown
<!-- ekline-ignore-next-line EK00001, EK00033 -->
Only those rules are ignored. Other rules still apply to this line.
```

### Ignoring the current line

Add the comment at the end of the line you want to ignore.

```markdown
The `oldParam` field is deprecated. <!-- ekline-ignore-line EK00001 -->
```

### Ignoring a section

Wrap content in start/end comments to ignore a block.

```markdown
Regular checked content here.

<!-- ekline-ignore-start -->
Everything in this section is ignored.
Multiple lines, code blocks, whatever you need.
<!-- ekline-ignore-end -->

Back to checked content.
```

**With specific rules:**
```markdown
<!-- ekline-ignore-start EK00001, EK00002 -->
Only the specified rules are ignored in this section.
<!-- ekline-ignore-end -->
```

### Ignoring an entire file

Place anywhere in the file (top recommended).

```markdown
<!-- ekline-ignore-file -->

# Auto-Generated Reference

All content in this file is ignored.
```

**With specific rules:**
```markdown
<!-- ekline-ignore-file EK00001 -->
```

### Adding reasons

Document why you're ignoring a rule. This helps future maintainers (including yourself) understand the decision.

```markdown
<!-- ekline-ignore-next-line EK00300 -- intentional for backwards compatibility -->
<!-- ekline-ignore-start EK00031 -- passive voice required by legal -->
<!-- ekline-ignore-file -- generated from OpenAPI spec -->
```

---

## Ignore files/directories

### Excluding files

For files that shouldn't be checked at all:

```json
{
  "contentDirectory": ["docs"],
  "excludeFiles": ["CHANGELOG.md", "generated/*.md"]
}
```

### Excluding directories

For directories that shouldn't be checked:

```json
{
  "contentDirectory": ["docs"],
  "excludeDirectories": ["node_modules", "api-reference/generated"]
}
```

<Aside type="tip">
Use `excludeFiles` and `excludeDirectories` for generated content. Use `ignore` for rules that don't fit your style. Use inline comments for specific exceptions in otherwise-checked content.
</Aside>

---

## Common scenarios

### Quotations you can't change

Customer quotes, legal text, or historical references often violate style rules intentionally.

```markdown
<!-- ekline-ignore-next-line EK00300 -- customer testimonial, preserve original spelling -->
"I definately love this product!" - Jane D.
```

### Legacy API naming

Old APIs sometimes have typos baked into their contracts.

```markdown
<!-- ekline-ignore-next-line EK00300 -- legacy API field name -->
The endpoint returns a `responce` object for backwards compatibility.
```

### Code examples with intentional "errors"

Documentation showing what not to do, or demonstrating error messages.

````markdown
<!-- ekline-ignore-start -- example of incorrect usage -->
```js
// DON'T do this - the parameter is misspelled
fetch('/api?qurey=test')
```
<!-- ekline-ignore-end -->
````

### Required passive voice

Legal text and formal contracts sometimes require passive voice.

```markdown
<!-- ekline-ignore-next-line EK00031 -- passive voice required by legal -->
The agreement must be signed by the customer before activation.
```

### Auto-generated files

Files generated from OpenAPI specs or other sources.

```markdown
<!-- ekline-ignore-file -- auto-generated from openapi.yaml -->
```

<Aside type="note">
For auto-generated files, consider using `excludeFiles` in your config instead of inline comments. That way you don't need to preserve the comment when regenerating.
</Aside>

---

## Best practices

### Prefer targeted ignores

Instead of ignoring all rules, target the specific rule causing the issue.

```markdown
// Bad - ignores everything
<!-- ekline-ignore-next-line -->

// Good - only ignores the specific rule
<!-- ekline-ignore-next-line EK00001 -->
```

### Always add reasons

A reason takes seconds to write and saves minutes of confusion later.

```markdown
// Bad - future you won't remember why
<!-- ekline-ignore-next-line EK00001 -->

// Good - clear intent
<!-- ekline-ignore-next-line EK00001 -- legacy API naming -->
```

### Review ignores periodically

Inline ignores can become stale. When updating documentation:
- Check if the ignored content still exists
- Check if the reason still applies
- Remove ignores that are no longer needed

### Use config for project-wide decisions

If you're adding the same inline ignore repeatedly, it's a sign you should use the config file instead.

```json
{
  "ignore": ["EK00042"]
}
```

---

## Behavior notes

- **Case insensitive**: `EKLINE-IGNORE-FILE` works the same as `ekline-ignore-file`
- **Flexible whitespace**: Extra spaces are tolerated
- **Code blocks excluded**: Comments inside fenced code blocks (` ``` `) are not processed
- **Unclosed sections**: `ekline-ignore-start` without `ekline-ignore-end` extends to end of file

---

## Next steps

- [CLI Reference](/reviewer/integrations/cli-integration) — Full config file options
- [Framework Support](/reviewer/configuration/framework-support) — MDX component handling