[insiders] Code block annotation alignment for comment lines

[kcgthb]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I've found a bug and checked that ...

• ... the problem doesn't occur with the mkdocs or readthedocs themes
• ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
• ... the documentation does not mention anything about my problem
• ... there are no open or closed issues that are related to my problem

Description

Code block annotations don't appear to be properly positioned on comment lines.

Expected behaviour

Properly aligned annotation mark.

Actual behaviour

The following Markdown:

# Annotation test
  
  ```shell
  #!/bin/bash
  #
  # this is a multi-line comment
  # that goes on and on # (1)
  # and ends here
  
  echo "not a comment" # (2)
  echo "the end"
  ```
  
  1. first annotation
  2. second annotation

generates the following code block:

• Annotation (1) is made on a commented line, and the marker is inserted as a new line in the block.
• Annotation (2) is made on a regular, non-comment line, and the marker properly aligned.

Steps to reproduce

Activate code block annotations in Insiders, and generated a code block with an annotation on a language-commented line.

Package versions

• Python: Python 3.9.7
• MkDocs: mkdocs, version 1.2.3
• Material: Version: 7.3.4+insiders.3.1.4

Configuration

theme:
  features:
    - content.code.annotate

System information

• Operating system: Linux
• Browser: Chrome

[squidfunk]

Thanks for reporting. That's indeed a limitation of the current implementation. Currently, if there's a code annotation in a comment, the whole line is eaten. I'm going to work on code annotations again shortly and also fix this one as well.

[kcgthb]

Got it, thank you!

[squidfunk]

Fixed in 8ebee733d.

Before this commit, a comment was entirely replaced when a code annotation was found in it. Now, comments are scanned for code annotations and the respective text nodes are split, only replacing the actual annotations. This allows for putting annotations inside comments (see bubble 1 and 2)

However, it also means that now the characters opening the comment, i.e. #, // etc. are kept (see bubble 3). Personally, I like it, but other users maybe don't. Thus, we might need a way to signal via annotation syntax that an annotation should replace the comments in its entirety, maybe something like (1)!. This however doesn't look as nice when rendered without JavaScript (with annotations not being available). Another way would be to detect whether a comment does solely contain a code annotation, but then we would also need some mechanism to detect what is a control character and what not, so it's probably better to let the user decide. Any mechanism must work with all languages.

I'm interested in feedback before pushing this out as part of a new release.

[squidfunk]

I had to reissue the latest release (my fault), so this has been released as part of 7.3.6+insiders-3.2.2. Sorry for any inconvenience this might be causing.