Is it possible to highlight code blocks via code comments?

[heitorlessa]

Perhaps it is possible, but we're using specific lines to highlight a given code block. While this served us well, we're now past 500+ code snippets and any refactoring / formatting means we're manually going to each code snippet to correct the line numbers to highlight.

Recent example: we're looking to add from __future__ import annotations, but this will shift line numbers breaking the highlight.

Idea: something like code annotation but to highlight. Perhaps it's possible with SuperFences but unsure where to begin.

Thanks a lot!

[kamilkrzyskow]

Hello @heitorlessa,
without looking into the details, I this this issue will need to be solved in similar spirit to:

• Hiding lines from code blocks #7113
• ollipa/chainmock@ebc425d

You need to use a hook to patch the internals of the highlight logic.
In your case you'd probably have to dynamically adjust the hl_lines="2 3" numbers based on some conditions after reading the code block source.
Due to lack of time I didn't check if the place where you need to patch/hook into is the same, but I guess it should be the same 🤔

[heitorlessa]

hey @kamilkrzyskow thanks a lot for the workaround; I'll open up a feature request instead. Patching internals sounds unstable, considering we have thousands of page views a day with over 500 code snippets.

Example of code snippet that would have to manually be edited if we add a new import line for example: https://docs.powertools.aws.dev/lambda/python/latest/utilities/batch/#recommended

[heitorlessa]

Feature request created: #7296

[kamilkrzyskow]

Sure, I get that any patching adds code debt for maintenance, and adds a locking dependency for other changes (like those comments would rely on the patch), but considering the stability of the implementation of Highlight.highlight over the last few years I don't think the patch would be unstable.

Also compared to the complexity of other code samples in your docs I don't think this patch would take long to maintain even if it breaks in a few years.
If time wouldn't temporarily allow to update the broken incompatible patch, then you could lock the mkdocs/mike version for the technical writers to be able to continue working.

Looking at the docs I also saw a lot of custom classes and types, which could also be highlighted using a custom Pygments lexer.
Here it's worth mentioning that custom lexers aren't cached, and I had to patch this months ago and it still works to this day.

• [Bug] Lexer lookup doesn't cache custom plugin lexers pygments/pygments#2479

What I'm trying to say is, being cautious is definitely good, however using a shabby code snippet written in 1 hour in production shouldn't be disallowed, as you can probably fix it in less time ;^)