squidfunk/mkdocs-material · error · RuntimeError

Unknown shortcode: {type}

Error message

Unknown shortcode: {type}

What it means

The shortcodes hook replaces <!-- md:... --> comments in documentation Markdown. Its replace() dispatches on the shortcode type (e.g. version, default, badge kinds); if the parsed type is not a known shortcode, it raises RuntimeError("Unknown shortcode: {type}"). This is a typo/protocol guard for the documentation authoring conventions.

Source

Thrown at src/overrides/hooks/shortcodes.py:65

            else:
                return _badge_for_version(args, page, files)
        elif type == "sponsors":     return _badge_for_sponsors(page, files)
        elif type == "flag":         return flag(args, page, files)
        elif type == "option":       return option(args)
        elif type == "setting":      return setting(args)
        elif type == "feature":      return _badge_for_feature(args, page, files)
        elif type == "plugin":       return _badge_for_plugin(args, page, files)
        elif type == "extension":    return _badge_for_extension(args, page, files)
        elif type == "utility":      return _badge_for_utility(args, page, files)
        elif type == "example": return _badge_for_example(args, page, files)
        elif type == "demo":         return _badge_for_demo(args, page, files)
        elif type == "default":
            if   args == "none":     return _badge_for_default_none(page, files)
            elif args == "computed": return _badge_for_default_computed(page, files)
            else:                    return _badge_for_default(args, page, files)

        # Otherwise, raise an error
        raise RuntimeError(f"Unknown shortcode: {type}")

    # Find and replace all external asset URLs in current page
    return re.sub(
        r"<!-- md:(\w+)(.*?) -->",
        replace, markdown, flags = re.I | re.M
    )

# -----------------------------------------------------------------------------
# Helper functions
# -----------------------------------------------------------------------------

# Create a flag of a specific type
def flag(args: str, page: Page, files: Files):
    type, *_ = args.split(" ", 1)
    if   type == "experimental":  return _badge_for_experimental(page, files)
    elif type == "required":      return _badge_for_required(page, files)
    elif type == "customization": return _badge_for_customization(page, files)
    elif type == "metadata":      return _badge_for_metadata(page, files)

View on GitHub (pinned to e2136532f4)

Solutions

1. Check the type word against the implemented shortcodes in overrides/hooks/shortcodes.py and fix the spelling in your Markdown.
2. If a new shortcode is needed, add a branch in replace() plus the badge/generator function it calls.
3. Search the repo for existing usages (<!-- md:...) as canonical examples.

Example fix

<!-- before -->
<!-- md:verison 9.0 -->

<!-- after -->
<!-- md:version 9.0 -->

import re
KNOWN = {"version", "flag", "default"}  # set from overrides/hooks/shortcodes.py
for m in re.finditer(r"<!-- md:(\w+)(.*?) -->", markdown, re.I | re.M):
    assert m.group(1).lower() in KNOWN, f"Unknown shortcode: {m.group(1)}"

def is_known_shortcode(type: str) -> bool:
    return type in {"version", "flag", "default"}

try:
    page_markdown = on_page_markdown(markdown, page, config, files)
except RuntimeError as e:
    if str(e).startswith("Unknown shortcode"):
        print("Fix or implement:", e)
    else:
        raise

When it happens

Trigger: Writing <!-- md:verison 1.0 --> or any <!-- md:xyz ... --> with a type not among the implemented shortcodes in overrides/hooks/shortcodes.py; the regex matches \w+ so any word becomes a candidate type.

Common situations: Copy-pasting shortcode syntax from another project or an outdated docs page; misspelling 'version', 'flag', 'default', etc.; inventing a new shortcode without implementing it in the hook.

Related errors

• Unknown type: {type}
• Relative path processor not registered
• Error reading filter configuration in '{key}': {e}
• Couldn't find author '{id}'
• Couldn't find '{separator}' in post '{path}' in '{docs}'

AI-assisted analysis of squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/454ecd56fb76d7f1. Report an issue: GitHub.