Multi color highlighting

[awdeorio]

Is your feature request related to a problem? Please describe. Explaining a larger code block is tricky. While highlighting is very helpful when there's one key point, it falls short when you have several points. For an example, see the EECS 485 P4 Sockets and waiting example and explanation.

Describe the solution you'd like It would be nice if I could highlight several different ranges of lines in several different colors. Then, in the text use some kind of visual clue to refer to the different colors in different paragraphs of the explanation.

Describe alternatives you've considered The current explanation copy-pastes a few lines at a time. This is less than ideal because the blocks are out of context.

I've also considered referring to line numbers. While this is accurate, it's a little harder to read from the student perspective.

Additional context I'm very open to suggestions here. Are there other better ways to explain more complex chunks of code?

[seshrs]

Thanks for the feedback! Yes, I definitely see the issue with explaining large codeblocks.

I’m hesitant about whether multi-color highlighting is the best solution though, especially from the point-of-view of accessibility (for students with color vision deficiencies).

Instead, what do you think about “callouts” that appear inside the codeblock and appear in the margin or to the right of the code? I’ll need to look for examples on other websites and give some thought to the API…

[seshrs]

Ah ha, found an example of “annotations”: https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations

Though I think I’d choose a slightly different API, and make it possible to add multi-line annotations.

Aside: I also really like Docusarus’ implementation of “magic comments” for highlighting ranges. I think I can implement that too! https://docusaurus.io/docs/markdown-features/code-blocks#highlighting-with-comments

[awdeorio]

Thanks for pushing back with better suggestions!

Ah ha, found an example of “annotations”

So basically pop-ups inline with code. One downside is that it might not be obvious that you should read this.

magic comments” for highlighting ranges.

Is the idea that you click something to change which lines are highlighted? That's cool! You could show 1 block of code. Show default (first) highlighting. Explain it in the following paragraph. Then in the next paragraph say "now we're talking about this other chunk. There's a link that causes the highlighting to shift.

[seshrs]

Is the idea that you click something to change which lines are highlighted?

Oh hmm, I hadn’t thought about that. I’ll need to think a bit more about that one.

Regarding magic comments, I was referring to using code block comments to indicate which lines should be highlighted, instead of specifying line numbers. (It would be easier for you as a spec author to see which lines are highlighted.)

[awdeorio]

Regarding magic comments, I was referring to using code block comments to indicate which lines should be highlighted, instead of specifying line numbers. (It would be easier for you as a spec author to see which lines are highlighted.)

Meh, I could take it or leave it with the magic comments.