docs: pymdownx.inlinehilite (via mkdocs-gallery) breaking autorefs

[tlambert03]

Hey @GenevieveBuckley,

I just noticed an unfortunate problem with mkdocs-gallery that might require a reversion of #571 . Any mkdocstrings link that uses backticks for formatting like [`magicgui.some.class`][] (which is a lot of them) breaks when mkdocs gallery is enabled, even if it's a file that has nothing to do with an example.

For example on the main widgets page:

with mkdocs-gallery enabled:

without mkdocs-gallery enabled:

[GenevieveBuckley]

Oh noooo 😢

[GenevieveBuckley]

I looked at this problem more today.

1. I have a PR open to fix the immediate issue in this repository docs: Fix broken mkdocs links #587
2. I tried figuring out the root cause of the issue, but wasn't able to reproduce it with a more minimal example repository.

See here for the example repository: https://github.com/GenevieveBuckley/test-mkdocs-links
Running mkdocs serve on that doesn't break the hyperlink in the same way we saw here in magicgui.

I originally thought there might be some bad interaction between the mkdocstrings and mkdocs-gallery plugins, but I didn't see that happening here. It's possible there is some sort of funky interaction going on when you make the configuration file more complicated & add more plugins (or add python gallery example scripts, or scripts involving pyqt, etc., etc.). I wonder if it's possibly the gallery_conf.py file, too?

I don't have any more time to dedicate to this, but wanted to share what I had anyway.

[tlambert03]

Thanks so much @GenevieveBuckley, I appreciate you taking a look and the minimal repo is very useful.

I'll take it from here and see what I can figure out

[tlambert03]

ok, I was able to determine that this isn't an issue with mkdocs-gallery per se, but rather the addition of pymdownx.inlinehilite to the markdown_extensions (which mkdocs gallery does implicitly). That breaks mkdocs-autorefs when using code backticks

With this mkdocs config:

site_name: My Docs
markdown_extensions:
  - pymdownx.inlinehilite
plugins:
  - mkdocstrings

I can reproduce the issue on a tiny little docs site:

This breaks:

# Welcome to MkDocs

[`thing.MyClass`][]

::: thing.MyClass

whereas using [thing.MyClass][] works fine.

[tlambert03]

related issue on autorefs here: mkdocstrings/autorefs#34

[GenevieveBuckley]

You narrowed that down impressively fast, nice work!