Highlight specific lines of code using comments

[heitorlessa]

Context

As of today, you can highlight lines using hl_lines= syntax when adding a code block. This is great when you start, or when you rarely update the code block.

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

As we grow way beyond 500 code snippets, we run into issues where sometimes a new import, or code snippet improvements break highlight. Two years ago we also added formatting and linting of all code snippets for quality and consistency, but it aggravated the issue at scale.

For example, if we make a minor update to the code snippet above it will break the highlight:

from __future__ import annotations

def bubble_sort(items: list):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Description

It'd be great to be able to highlight a specific code line using comments. For example:

def bubble_sort(items):
    for i in range(len(items)):  # hl
        for j in range(len(items) - 1 - i):  # hl
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

This removes the need to manually fix each code snippet hl_lines whenever there's a change in the code that shifts the line number where the highlight is. This is similar to the great code annotation feature today, whereas instead of # (1) we'd use another term to highlight it.

Related links

• Requesting a change
• Code highlight
• Discussion that triggered a feature request

Use Cases

In our case, we want to add from __future__ import annotations to all code snippets for older Python versions (e.g., Python 3.8), along with other enhancements. This however would turn into days of work to change, format, lint, verify, and fix each code highlighted line we had before / after the change.

Off the top of my head, this would benefit people:

• supporting multiple versions of a given programming language, where code is largely the same with syntax/idioms differences
• large documentation with code snippets being refactored
• any documentation size where code snippets are updated on a regular basis
• documentation websites that use formatting, linting, and testing tools at CI to ensure code snippets are testable

One of the examples that would break should we make that change: https://docs.powertools.aws.dev/lambda/python/latest/utilities/batch/#recommended

Visuals

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting! Definitely a sound use case, and yes, the current situation is not ideal.

Line highlighting is implemented in pymdownx.highlight. I'd recommend taking this upstream to Python Markdown Extensions, as it's the package that provides the original highlighting functionality. Code annotations are mounted in the browser (with non-JS fallback), but highlighting needs to be implemented in Python a we would have no fallback, with no lines being highlighted without JS. It might be an extension to the current parser or some custom SuperFences logic.

I'm taking this back with me to the drawing board where I'm currently at, thinking deeply about the UX/DX/AX of Material for MkDocs. For now, we'd consider this upstream, but we'll look into improving the highlighting capabilities.

[squidfunk]

Just another idea: as mentioned, you could write a simple custom fence that pre-processes each code block looking for # hl or even # hl:start and # hl:end comments to support multi-line highlighting. This fence would then extract and remove those from the code block and configure pygments with the appropriate hl_lines. If that proves to be viable, we can think about abstracting this further and bring it to the Material for MkDocs code base.

[heitorlessa]

Got any quick link on how to write and package one as part of the build? I might be able to do that over next weekend :)

…

On Wed, 26 Jun 2024 at 11:11, Martin Donath ***@***.***> wrote: Just another idea: as mentioned, you could write a simple custom fence that pre-processes each code block looking for # hl or even # hl:start and # hl:end comments to support multi-line highlighting. This fence would then extract and remove those from the code block and configure pygments with the appropriate hl_lines. If that proves to be viable, we can think about abstracting this further and bring it to the Material for MkDocs code base. — Reply to this email directly, view it on GitHub <#7296 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZPQBAKQS2RFGWBZOXOSM3ZJKAS5AVCNFSM6AAAAABJ5JB77KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCOJRGIYDENJVHA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[alexvoss]

The documentation for custom fences should contain all you need. One thing I am not sure about is how to do some processing and then allow the standard processing to take place afterwards. Perhaps @facelessuser can comment on that. Would it be possible to modify the code block in a validator and return False from it to pass through to the next validator/formatter?

[squidfunk]

Hmm, I searched but no, not really, except for the official documentation on custom fences. Maybe @facelessuser has a quick snippet where a custom fence extends / pre-configures the functionality of another fence? As TL;DR, turning this:

``` py
def bubble_sort(items):
    for i in range(len(items)):  # hl
        for j in range(len(items) - 1 - i):  # hl
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j] #hl
```

Into this:

``` py hl_lines="2-3,5"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i): 
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

... and then feeding it into Pygments.

[squidfunk]

@alexvoss is faster than Lucky Luke 🤠 Sorry for double-tagging, Issac.