{"record":{"id":"64d877fdbd364057","repo":"squidfunk/mkdocs-material","slug":"error-reading-metadata-of-post-path-in-docs","errorCode":null,"errorMessage":"Error reading metadata of post '{path}' in '{docs}':\nExpected metadata to be defined but found nothing","messagePattern":"Error reading metadata of post '(.+?)' in '(.+?)':\nExpected metadata to be defined but found nothing","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/blog/structure/__init__.py","lineNumber":73,"sourceCode":"\n        # Resolve path relative to docs directory\n        docs = os.path.relpath(config.docs_dir)\n        path = os.path.relpath(file.abs_src_path, docs)\n\n        # Read contents and metadata immediately\n        with open(file.abs_src_path, encoding = \"utf-8-sig\") as f:\n            self.markdown = f.read()\n\n            # Sadly, MkDocs swallows any exceptions that occur during parsing.\n            # Since we want to provide the best possible user experience, we\n            # need to catch errors early and display them nicely. We decided to\n            # drop support for MkDocs' MultiMarkdown syntax, because it is not\n            # correctly implemented anyway. When using MultiMarkdown syntax, all\n            # date formats are returned as strings and list are not properly\n            # supported. Thus, we just use the relevants parts of `get_data`.\n            match: Match = YAML_RE.match(self.markdown)\n            if not match:\n                raise PluginError(\n                    f\"Error reading metadata of post '{path}' in '{docs}':\\n\"\n                    f\"Expected metadata to be defined but found nothing\"\n                )\n\n            # Extract metadata and parse as YAML\n            try:\n                self.meta = yaml.load(match.group(1), SafeLoader) or {}\n                self.markdown = self.markdown[match.end():].lstrip(\"\\n\")\n\n            # The post's metadata could not be parsed because of a syntax error,\n            # which we display to the author with a nice error message\n            except Exception as e:\n                raise PluginError(\n                    f\"Error reading metadata of post '{path}' in '{docs}':\\n\"\n                    f\"{e}\"\n                )\n\n            # Hack: if the meta plugin is registered, we need to move the call","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/blog/structure/__init__.py#L55-L91","documentation":"Blog posts must start with a YAML metadata block delimited by `---` lines, parsed via YAML_RE. If the regex finds no metadata block at the top of the markdown file, the Post constructor raises this PluginError because the plugin expects required metadata (title, date, etc.) to be defined.","triggerScenarios":"A file inside the blog `posts_dir` has no leading `--- ... ---` metadata block, or the block is malformed such that YAML_RE does not match (e.g. missing opening/closing `---`, BOM, or leading blank/comment lines before the block).","commonSituations":"Adding a plain markdown note into the posts directory; deleting the metadata while editing; an editor stripping the front-matter; a file with Windows BOM or different fence characters.","solutions":["Add a proper metadata block at the very top of the post: first line `---`, metadata, then a closing `---`","Remove or move the file out of the configured `posts_dir` if it is not a blog post","Check for a BOM or stray characters before the opening `---` and remove them"],"exampleFix":"# before (posts/my-post.md)\n# My Post\nSome text\n\n// after\n---\ntitle: My Post\ndate: 2024-01-15\n---\n# My Post\nSome text","handlingStrategy":"validation","validationCode":"import pathlib\ndef has_front_matter(p):\n    text = p.read_text(encoding='utf-8-sig')\n    return text.startswith('---') and '\\n---' in text[3:]\nmissing = [p for p in pathlib.Path('docs/posts').rglob('*.md') if not has_front_matter(p)]\nassert not missing, f\"Posts missing front matter: {missing}\"\n","typeGuard":"def has_valid_front_matter(text):\n    stripped = text.lstrip('\\ufeff')\n    return stripped.startswith('---') and stripped.count('---') >= 2\n","tryCatchPattern":"try:\n    mkdocs.commands.build(config)\nexcept PluginError as e:\n    if \"Expected metadata to be defined\" in str(e):\n        log.error(f\"Add a '--- ... ---' metadata block to: {e}\")\n    raise\n","preventionTips":["Always start blog posts with a `---` metadata block including at least title and date","Never put non-post markdown files into the configured posts_dir","Save files as UTF-8 without BOM","Use an editor snippet/template for new posts to guarantee the front-matter"],"tags":["mkdocs","blog-plugin","front-matter","yaml"],"backgroundTag":"missing-front-matter","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}