{"record":{"id":"454ecd56fb76d7f1","repo":"squidfunk/mkdocs-material","slug":"unknown-shortcode-type","errorCode":null,"errorMessage":"Unknown shortcode: {type}","messagePattern":"Unknown shortcode: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/overrides/hooks/shortcodes.py","lineNumber":65,"sourceCode":"            else:\n                return _badge_for_version(args, page, files)\n        elif type == \"sponsors\":     return _badge_for_sponsors(page, files)\n        elif type == \"flag\":         return flag(args, page, files)\n        elif type == \"option\":       return option(args)\n        elif type == \"setting\":      return setting(args)\n        elif type == \"feature\":      return _badge_for_feature(args, page, files)\n        elif type == \"plugin\":       return _badge_for_plugin(args, page, files)\n        elif type == \"extension\":    return _badge_for_extension(args, page, files)\n        elif type == \"utility\":      return _badge_for_utility(args, page, files)\n        elif type == \"example\": return _badge_for_example(args, page, files)\n        elif type == \"demo\":         return _badge_for_demo(args, page, files)\n        elif type == \"default\":\n            if   args == \"none\":     return _badge_for_default_none(page, files)\n            elif args == \"computed\": return _badge_for_default_computed(page, files)\n            else:                    return _badge_for_default(args, page, files)\n\n        # Otherwise, raise an error\n        raise RuntimeError(f\"Unknown shortcode: {type}\")\n\n    # Find and replace all external asset URLs in current page\n    return re.sub(\n        r\"<!-- md:(\\w+)(.*?) -->\",\n        replace, markdown, flags = re.I | re.M\n    )\n\n# -----------------------------------------------------------------------------\n# Helper functions\n# -----------------------------------------------------------------------------\n\n# Create a flag of a specific type\ndef flag(args: str, page: Page, files: Files):\n    type, *_ = args.split(\" \", 1)\n    if   type == \"experimental\":  return _badge_for_experimental(page, files)\n    elif type == \"required\":      return _badge_for_required(page, files)\n    elif type == \"customization\": return _badge_for_customization(page, files)\n    elif type == \"metadata\":      return _badge_for_metadata(page, files)","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/overrides/hooks/shortcodes.py#L47-L83","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the type word against the implemented shortcodes in overrides/hooks/shortcodes.py and fix the spelling in your Markdown.","If a new shortcode is needed, add a branch in replace() plus the badge/generator function it calls.","Search the repo for existing usages (<!-- md:...) as canonical examples."],"exampleFix":"<!-- before -->\n<!-- md:verison 9.0 -->\n\n<!-- after -->\n<!-- md:version 9.0 -->","handlingStrategy":"validation","validationCode":"import re\nKNOWN = {\"version\", \"flag\", \"default\"}  # set from overrides/hooks/shortcodes.py\nfor m in re.finditer(r\"<!-- md:(\\w+)(.*?) -->\", markdown, re.I | re.M):\n    assert m.group(1).lower() in KNOWN, f\"Unknown shortcode: {m.group(1)}\"","typeGuard":"def is_known_shortcode(type: str) -> bool:\n    return type in {\"version\", \"flag\", \"default\"}","tryCatchPattern":"try:\n    page_markdown = on_page_markdown(markdown, page, config, files)\nexcept RuntimeError as e:\n    if str(e).startswith(\"Unknown shortcode\"):\n        print(\"Fix or implement:\", e)\n    else:\n        raise","preventionTips":["Keep a snippet/IDE template of valid <!-- md:... --> shortcodes.","Grep the docs tree for md: comments and diff their type words against implemented ones in CI.","Never invent shortcodes without adding a branch in replace().","Copy shortcode examples from existing, building pages."],"tags":["python","mkdocs","shortcodes","documentation"],"backgroundTag":"unknown-shortcode","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}