Is there a way to debug code annotations?

[Andre601]

I currently encounter an issue with using Code annotations, but I'm unsure what happens here exactly or why it happens.

The issue I encounter is, that when I press the icon, I get moved to it, but no content is showing at all.
I tried checking the browser console to see if there are any issues, but nothing gets reported there.

This is the section I have an issue with:

```java { .annotate }
public class MyPlaceholders extends PlaceholderProvider {
    
    public MyPlaceholders(String identifier) {
        super(identifier); // (1)
    }
    
    @Override
    public String parsePlaceholder(String placeholder, GenericPlayer player, GenericServer server) {
        return null;
    }
}
```

1.  It's recommended to replace this constructor with a No-Args Constructor and have the placeholder name set in the `super` call:  
    ```java
    public MyPlaceholders() {
        super("myplaceholders");
    }
    ```

My current guess is, that it may be some conflict with JS? I'm using a separate JS code to fetch data to inject into the page where I also have this code block, so maybe something there causes a conflict?

Here's the JS file I use, just in case:

Details

document$.subscribe(async () => {
    const url = 'https://api.allorigins.win/raw?url='
    const apiUrl = `https://api.allorigins.win/raw?url=${encodeURIComponent('https://codeberg.org/api/v1/repos/Andre601/asl-api/releases/latest')}`

    const repo_stats = document.querySelector('[data-md-component="source"] .md-source__repository');
    
    function loadCodebergInfo(data) {
        const facts = document.createElement("ul");
        facts.className = "md-source__facts";
        
        const version = document.createElement("li");
        version.className = "md-source__fact md-source__fact--version";
        
        const stars = document.createElement("li");
        stars.className = "md-source__fact md-source__fact--stars";
        
        const forks = document.createElement("li");
        forks.className = "md-source__fact md-source__fact--forks";
        
        version.innerText = data["version"];
        stars.innerText = data["stars"];
        forks.innerText = data["forks"];
        
        facts.appendChild(version);
        facts.appendChild(stars);
        facts.appendChild(forks);
        
        repo_stats.appendChild(facts);
    }
    
    function loadApiInfo(data) {
        const version = data["version"];
        const versionToken = '{apiVersion}';
        const codeBlocks = document.querySelectorAll('.md-content pre code');
        for(const codeBlock of codeBlocks) {
            codeBlock.innerHTML = codeBlock.innerHTML.replace(new RegExp(versionToken, 'g'), version.substring(1));
        }
    }
    
    function loadPluginVersion(data) {
        const version = data["version"];
        const versionToken = '{version}'
        const entries = document.querySelectorAll('.md-content code');
        for(const entry of entries) {
            entry.innerHTML = entry.innerHTML.replace(new RegExp(versionToken, 'g'), version.substring(1));
        }
    }
    
    async function fetchApiInfo() {
        const tag = await fetch(`${apiUrl}`)
            .then(_ => _.json());
        
        const data = {
            "version": tag.tag_name
        };
        
        __md_set("__api_tag", data, sessionStorage);
        loadApiInfo(data);
    }
    
    async function fetchInfo() {
        const [release, repo] = await Promise.all([
            fetch(`${url}${encodeURIComponent('https://codeberg.org/api/v1/repos/Andre601/AdvancedServerList/releases/latest')}`).then(_ => _.json()),
            fetch(`${url}${encodeURIComponent('https://codeberg.org/api/v1/repos/Andre601/AdvancedServerList')}`).then(_ => _.json()),
        ]);
        
        const data = {
            "version": release.tag_name,
            "stars": repo.stars_count,
            "forks": repo.forks_count
        };
        
        __md_set("__git_repo", data, sessionStorage);
        loadCodebergInfo(data);
        loadPluginVersion(data);
    }
    
    if(!document.querySelector('[data-md-component="source"] .md-source__facts')) {
        const cached = __md_get("__git_repo", sessionStorage);
        if((cached != null) && (cached["version"])) {
            loadCodebergInfo(cached);
            loadPluginVersion(cached);
        } else {
            fetchInfo();
        }
    }
    
    if(location.href.includes('/api/')) {
        const cachedApi = __md_get("__api_tag", sessionStorage);
        if((cachedApi != null) && (cachedApi["version"])) {
            loadApiInfo(cachedApi);
        } else {
            fetchApiInfo();
        }
    }
})

I really don't know what could be the problems here... So if there is any way to debug code annotations, I would apreciate it.

[Andre601]

To clarify: The annotation is being created, so it does recognize the ordered list after the code block. But it for some reason does not display the Content on click, so either it doesn't get created properly, or gets blocked it seems...

[Andre601]

Looking further into this, it seems the site's HTML gets somewhat messed up, as by the looks of it is the HTML for the Annotation already there despite not being "opened" while on the Material docs example, the content only appears when pressed.

This is further proven by the fact, that the annotation gets highlighted, despite the mouse not being near it, most likely because it hovers over the (currently invisible?) content.

[kamilkrzyskow]

Hello @Andre601,
please create a minimal runnable reproduction archive to limit the scope of possible causes.

As for the question in the title, you could try setting a global/general breakpoint for all mousedown events in your browser Dev Tools and see what will happen if you step over the code execution. I think that the .js.map file should be included during mkdocs serve 🤔

You mentioned there is an issue with the formatting of the HTML, so perhaps the 4 spaces of indentation for the codeblock in the list item are the issue. Speaking of list items, you could try using the md_in_html extension to use a <li markdown> tag and wrap the content properly.

[kamilkrzyskow]

Without a runnable reproduction I can't really debug it 🤔

However, since it's related to the codeBlock.innerHTML = ... assignment then, the logic which controls the annotations likely stores the memory reference of the HTML tags during load. By doing a innerHTML assignment you're basically deleting the previous tags in the DOM and the memory references become lost.

My best suggestion currently would be to be more fine-grained with the replacement of the code block content.
Loop over the tags inside it, and replace the innerText of each singular tag instead of the whole HTML structure of the root code block. Pay attention to target the tags at the "bottom" of the DOM tree without any HTML inside them, as replacing the innerText midway will remove HTML tags along the way.

[Andre601]

Played around a bit.
I first tried to make the selector more specific by adding a data-md-component="api-version" attribute to the Code block section (the div), but that didn't change a thing.
So I removed all the JS responsible for replacing the {apiVersion} text in the HTML... and this still is an issue.

So it seems that the pure existance of this JS seems to cause the issue... Perhaps because I subscribe to the document here and that any rewrites seem to cause issues?
Even tho the code used here for the other part - displaying repository stats in the top-right because Forgejo isn't supported by Material for MkDocs - is pretty much the same of what is used by Material for MkDocs itself to obtain stats from GitHub... At least last time I checked it was.

[Andre601]

Also, the current selector (div[data-md-component="api-version"] pre code) is as close as I can make a selection here, as the {apiVersion} is just there in the code tag, not surrounded by anything.

[Andre601]

I finally got something to work here...

The issue was indeed the replacement of the HTML, which seems to remove listeners, which annotations for sure register.
One solution is to create and use a TreeWalker, as that one preserves pre-existing listeners. Issue here was, that it only accepts a single Node and not multiple (i.e. those returned from querySelectorAll) and querySelector only returns the first match.

So solution here was to use querySelectorAll and call forEach to then apply a treewalker on each element in it.
I don't know if that can be improved, but it seems to work for now.

My full JS:

document$.subscribe(async () => {
    const url = 'https://api.allorigins.win/raw?url='
    const apiUrl = `https://api.allorigins.win/raw?url=${encodeURIComponent('https://codeberg.org/api/v1/repos/Andre601/asl-api/releases/latest')}`

    const repo_stats = document.querySelector('[data-md-component="source"] .md-source__repository');
    
    async function loadCodebergInfo(data) {
        const facts = document.createElement("ul");
        facts.className = "md-source__facts";
        
        const version = document.createElement("li");
        version.className = "md-source__fact md-source__fact--version";
        
        const stars = document.createElement("li");
        stars.className = "md-source__fact md-source__fact--stars";
        
        const forks = document.createElement("li");
        forks.className = "md-source__fact md-source__fact--forks";
        
        version.innerText = data["version"];
        stars.innerText = data["stars"];
        forks.innerText = data["forks"];
        
        facts.appendChild(version);
        facts.appendChild(stars);
        facts.appendChild(forks);
        
        repo_stats.appendChild(facts);
    }
    
    async function loadApiInfo(data) {
        const codeBlocks = document.querySelectorAll('[data-md-component="api-version"] pre code')
        if (codeBlocks === null)
            return;
        
        const version = data["version"];
        const regex = new RegExp('{apiVersion}', 'g');
        codeBlocks.forEach((codeBlock) => {
            var walker = document.createTreeWalker(codeBlock, NodeFilter.SHOW_TEXT);
            var node;
            while (node = walker.nextNode()) {
                node.nodeValue = node.nodeValue.replace(regex, version.substring(1));
            }
        });
    }
    
    async function loadPluginVersion(data) {
        const entries = document.querySelectorAll('code[data-md-component="plugin-version"]');
        if(entries === null)
            return;
        
        const version = data["version"];
        const regex = new RegExp('{version}', 'g');
        entries.forEach((entry) => {
            var walker = document.createTreeWalker(entry, NodeFilter.SHOW_TEXT);
            var node;
            while (node = walker.nextNode()) {
                node.nodeValue = node.nodeValue.replace(regex, version.substring(1));
            }
        })
    }
    
    async function fetchApiInfo() {
        const tag = await fetch(`${apiUrl}`)
            .then(_ => _.json());
        
        const data = {
            "version": tag.tag_name
        };
        
        __md_set("__api_tag", data, sessionStorage);
        loadApiInfo(data);
    }
    
    async function fetchInfo() {
        const [release, repo] = await Promise.all([
            fetch(`${url}${encodeURIComponent('https://codeberg.org/api/v1/repos/Andre601/AdvancedServerList/releases/latest')}`).then(_ => _.json()),
            fetch(`${url}${encodeURIComponent('https://codeberg.org/api/v1/repos/Andre601/AdvancedServerList')}`).then(_ => _.json()),
        ]);
        
        const data = {
            "version": release.tag_name,
            "stars": repo.stars_count,
            "forks": repo.forks_count
        };
        
        __md_set("__git_repo", data, sessionStorage);
        loadCodebergInfo(data);
        loadPluginVersion(data);
    }
    
    if(!document.querySelector('[data-md-component="source"] .md-source__facts')) {
        const cached = __md_get("__git_repo", sessionStorage);
        if((cached != null) && (cached["version"])) {
            loadCodebergInfo(cached);
            loadPluginVersion(cached);
        } else {
            fetchInfo();
        }
    }
    
    if(location.href.includes('/api/')) {
        const cachedApi = __md_get("__api_tag", sessionStorage);
        if((cachedApi != null) && (cachedApi["version"])) {
            loadApiInfo(cachedApi);
        } else {
            fetchApiInfo();
        }
    }
})