search

backstage / mkdocs-techdocs-core

The core MkDocs plugin used by Backstage's TechDocs as a wrapper around multiple MkDocs plugins and Python Markdown extensions
Apache License 2.0
87 stars 62 forks source link

Cannot override config of extensions appended in techdocs-core #220

Open kunickiaj opened 4 days ago

kunickiaj commented 4 days ago

For example, if one wants to enable slugify on content tabs, they cant because the extension is always appended even if already configured in the user's mkdocs.yml

I saw https://github.com/backstage/mkdocs-techdocs-core/pull/214 which i think intended to address this issue, but i still cant get configuration to get merged with the default atechdocs one.

https://github.com/backstage/mkdocs-techdocs-core/blob/8bc1e2a79dc56f160458f6a8ab65393277a01456/src/core.py#L127

Have also tried

plugins:
  - techdocs-core
markdown_extensions:
  - pymdownx.extra:
      pymdownx.tabbed:
        slugify: !!python/object/apply:pymdownx.slugs.slugify
          kwds:
            case: lower

I suspect the issue is that while #214 removed the superfences plugin from the list of appended, it did not remove the others provided by pymdownx.extra still resulting in impossible configuration for those.

kunickiaj commented 4 days ago

After some more investigation I see that the config is correctly applied in normal mkdocs serve (on 8080) even with the techdocs-core plugin added so it seems something is being stripped out (dont know if this depends on some js) but something in techdocs is preventing the generation of the slugified anchor links.