Are Explicit Tags in mkdocs config supported in readthedocs? - read-the-docs

Question

I've been working on writing some mkdocs documentation which includes mermaid diagrams that I'd like to keep in the markdown files instead of turning into images and embedding them
I came across this great solution here: https://github.com/squidfunk/mkdocs-material/issues/693#issuecomment-411885426
Which uses the super-fences feature of the pymdown-extensions plugin to create a custom code block which renders the mermaid diagrams inside the code block.
It works in mkdocs running locally, but when I submit the configuration file to readthedocs it fails the yaml validation
Your mkdocs.yml could not be loaded, possibly due to a syntax error (line 18, column 19)
Line 18 in the mkdocs.yml config file is the section which calls the superfences python class
format: !!python/name:pymdownx.superfences.fence_div_format
Looking in the yaml specification https://yaml.org/spec/1.2/spec.html Shows that !! is for an explicit tag and it seems to have been part of the spec for quite some time ( back to version 1). I've tried making the value a string but this then causes issue with python reading it as a string
Does anyone know if readthedocs supports this or have you been able to get this working some other way?

Answer 1

ReadTheDocs is parsing the mkdocs.yaml file using pyyaml and it seems that it does not recognize !!.
For example:
>>> import yaml
>>> document = """
a: 1
b:
c: 3
d: !!4
"""
>>> print(yaml.dump(yaml.load(document)))
<stdin>:1: YAMLLoadWarning: calling yaml.load() without Loader=... is deprecated, as the default Loader is unsafe. Please read https://msg.pyyaml.org/load for full details.
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3.8/site-packages/yaml/__init__.py", line 114, in load
return loader.get_single_data()
File "/usr/lib/python3.8/site-packages/yaml/constructor.py", line 51, in get_single_data
return self.construct_document(node)
File "/usr/lib/python3.8/site-packages/yaml/constructor.py", line 60, in construct_document
for dummy in generator:
File "/usr/lib/python3.8/site-packages/yaml/constructor.py", line 413, in construct_yaml_map
value = self.construct_mapping(node)
File "/usr/lib/python3.8/site-packages/yaml/constructor.py", line 218, in construct_mapping
return super().construct_mapping(node, deep=deep)
File "/usr/lib/python3.8/site-packages/yaml/constructor.py", line 143, in construct_mapping
value = self.construct_object(value_node, deep=deep)
File "/usr/lib/python3.8/site-packages/yaml/constructor.py", line 100, in construct_object
data = constructor(self, node)
File "/usr/lib/python3.8/site-packages/yaml/constructor.py", line 427, in construct_undefined
raise ConstructorError(None, None,
yaml.constructor.ConstructorError: could not determine a constructor for the tag 'tag:yaml.org,2002:4'
in "<unicode string>", line 5, column 8:
d: !!4
^
>>>
See: https://github.com/readthedocs/readthedocs.org/issues/6889