Closed rmartine-ias closed 7 months ago
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
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.
still an issue
We are also looking to use annotations. Related issue #145 for updates on core packages relevant as well
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.
Something
techdocs-core
is doing (maybe settingtheme.palette
to''
?) prevents code annotations from rendering.Reproduction:
mkdocs.yml
:docs/index.md
: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.