Code annotations fail to render with techdocs-core plugin enabled

[rmartine-ias]

Something techdocs-core is doing (maybe setting theme.palette to ''?) prevents code annotations from rendering.

Reproduction:

python3.11 -m venv .venv
source .venv/bin/activate
pip install mkdocs-techdocs-core
mkdir docs

mkdocs.yml:

site_name: Backstage Docs
theme:
  name: material
  features:
    - content.code.annotate
nav:
  - Home: index.md
markdown_extensions:
  - pymdownx.superfences

docs/index.md:

```yaml
# (1)
```

1. An annotation

mkdocs build
open site/index.html # You should see a clickable annotation
yq -i '.plugins[0] = "techdocs-core"' mkdocs.yml
mkdocs build
open site/index.html # You should not see an annotation

Without techdocs:

With it:

I noticed that if I have no plugins set, and set theme.palette to "", then annotations also fail to render. So I think this might be causing it, but don't see an easy fix.

[steven-terrana-bah]

I came to the same conclusion that this issue was being caused by theme.palette: "" so i tried creating a hook that overrides this value after the techdocs-core plugin makes its configuration changes (just to see what would happen).

This fixed code annotation rendering on the mkdocs site directly (http://localhost:8000) but not in the techdocs rendering within backstage (http://localhost:3000) when running techdocs-cli serve.

mkdocs.yml

site_name: test-annotations

theme:
  name: material
  features:
    - content.code.annotate 

plugins: 
 - techdocs-core

hooks:
- hooks.py

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

nav:
  - home: index.md

hook.py

import mkdocs

@mkdocs.plugins.event_priority(-100)
def on_config(config):
    config['theme']['palette'] = {}
    config['theme']['palette']['scheme'] = 'default'
    return config

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[rmartine-ias]

still an issue

[Gholie]

We are also looking to use annotations. Related issue #145 for updates on core packages relevant as well

[alexlorenzi]

Hi, @rmartine-ias.
Thanks for spotting this, it certainly does mess up the HTML generated. We have an update going in that will fix this issue.

However, two other issues mean the annotations don't display from within Backstage:

First, we sanitize the HTML rendered by MkDocs in the TechDoc plugin before we display it on the page. This will remove the script tags that are generated by the plugin for the annotations.

Second, even if we modified the sanitization to keep the scripts, the way the rendered DOM is attached to the page still means that the javascript doesn't execute. We use the DomParser to convert the HTML string into DOM elements, and through this, any script tags get marked as unexecutable.

Because of this, we'd require quite a drastic change to how the frontend plugin works to enable this, so it's not something we can support currently.