check-code-block-highlights

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 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:

`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:

`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