check-code-block-highlights by nextflow-io

---
name: Check Code Block Highlights
description: Verify that hl_lines attributes in markdown code blocks correctly highlight the intended lines. Use when reviewing documentation with code examples, especially Before/After comparisons, or when highlights seem incorrect.
---

# Check Code Block Highlights

Verify that `hl_lines` attributes in markdown code blocks are correctly set to highlight the intended lines.

See [../shared/repo-conventions.md](../shared/repo-conventions.md) for file conventions.

## Critical Understanding

**`hl_lines` is snippet-relative, NOT related to `linenums`**:

- `linenums="21"` sets the _displayed_ starting line number
- `hl_lines="3"` highlights the _3rd line of the snippet_ (which displays as line 23)
- These are completely independent attributes

Example:

```markdown
`groovy linenums="21" hl_lines="3"
process FOO {      <- displayed as line 21 (snippet line 1)
    input:         <- displayed as line 22 (snippet line 2)
    val x          <- displayed as line 23 (snippet line 3) - HIGHLIGHTED
}
`
```

## How to Check

For each code block with `hl_lines`:

1. **Identify the code block** - Find blocks with `hl_lines="..."` attribute

2. **Count snippet lines** - Number each line of the code block starting from 1:

   ```
   1: #!/usr/bin/env nextflow
   2: (blank line)
   3: process FOO {
   4:     publishDir 'results'  <- if this should be highlighted, hl_lines should include "4"
   ...
   ```

3. **Verify intent** - For Before/After blocks:

   - "After" should highlight the NEW or CHANGED lines
   - "Before" should highlight the lines that WILL change (same content positions)
   - Both blocks should highlight corresponding lines showing the difference

4. **Check for common errors**:
   - Off-by-one errors (highlighting blank lines instead of code)
   - Confusing `linenums` with `hl_lines` (thinking hl_lines="21" highlights displayed line 21)
   - Highlighting section headers (`input:`, `output:`) instead of the actual values

## Fixing Issues

When you find incorrect highlights:

1. Count the actual line positions in the snippet (1-indexed)
2. Identify which lines contain the meaningful changes
3. Update `hl_lines` to reference those snippet line numbers
4. Verify Before/After blocks highlight corresponding positions

## Output Format

For each file checked, report:

```
## [filename]

### Block at line [N]: [description]
- Current: hl_lines="X Y Z"
- Lines X, Y, Z contain: [what's on those lines]
- Issue: [description of problem, if any]
- Suggested fix: hl_lines="A B C" (highlighting [what those lines contain])

### Summary
- Blocks checked: N
- Issues found: M
- [List of fixes needed]
```

## Example Analysis

Given this code block:

```markdown
`groovy title="example.nf" linenums="1" hl_lines="8 11 14"
#!/usr/bin/env nextflow       <- snippet line 1
                              <- snippet line 2 (blank)
process SAY_HELLO {           <- snippet line 3
                              <- snippet line 4 (blank)
    publishDir 'results'      <- snippet line 5
                              <- snippet line 6 (blank)
    input:                    <- snippet line 7
        val greeting          <- snippet line 8 - HIGHLIGHTED
                              <- snippet line 9 (blank)
    output:                   <- snippet line 10
        path "*.txt"          <- snippet line 11 - HIGHLIGHTED
                              <- snippet line 12 (blank)
    script:                   <- snippet line 13
        """echo hi"""         <- snippet line 14 - HIGHLIGHTED
}
`
```

Analysis: `hl_lines="8 11 14"` correctly highlights the input value (line 8), output value (line 11), and script content (line 14).

## Notes

- Blank lines count! They're common sources of off-by-one errors
- In Before/After comparisons, both blocks should highlight the same conceptual elements
- When in doubt, count every line including blanks and comments