squidfunk/mkdocs-material · error · PluginError

Error reading categories of post '{path}' in '{docs}': categ

Error message

Error reading categories of post '{path}' in '{docs}': category '{name}' not in allow list

What it means

The mkdocs-material blog plugin only creates category view pages for categories listed in the plugin's `categories_allowed` configuration option. When a post's YAML metadata declares a category that is not in that allow list, `_generate_categories` (invoked from the `on_files` event) aborts the build with this PluginError. The allow list must be non-empty; if it is empty the plugin falls back to treating the post's own category name as allowed.

Source

Thrown at src/plugins/blog/plugin.py:588

                yield Archive(name, file, config)

            # Assign post to archive
            assert isinstance(file.page, Archive)
            file.page.posts.append(post)

    # Generate views for categories - analyze posts and generate the necessary
    # views, taking the allowed categories as set by the author into account
    def _generate_categories(self, config: MkDocsConfig, files: Files):
        for post in self.blog.posts:
            for name in post.config.categories:
                path = self._format_path_for_category(name)

                # Ensure category is in non-empty allow list
                categories = self.config.categories_allowed or [name]
                if name not in categories:
                    docs = os.path.relpath(config.docs_dir)
                    path = os.path.relpath(post.file.abs_src_path, docs)
                    raise PluginError(
                        f"Error reading categories of post '{path}' in "
                        f"'{docs}': category '{name}' not in allow list"
                    )

                # Create file for view, if it does not exist
                file = files.get_file_from_path(path)
                if not file:
                    file = self._path_to_file(path, config)
                    files.append(file)

                    # Create file in temporary directory
                    self._save_to_file(file.abs_src_path, f"# {name}")

                # Temporarily remove view from navigation
                file.inclusion = InclusionLevel.EXCLUDED

                # Create and yield view
                if not isinstance(file.page, Category):

View on GitHub (pinned to e2136532f4)

Solutions

Add the missing category name to `categories_allowed` under the blog plugin settings in mkdocs.yml
Fix the typo/case mismatch in the post's `categories` metadata so it matches the allow list
Remove the `categories` key from the post if it should not be categorized

Example fix

# before (mkdocs.yml)
plugins:
  - blog:
      categories_allowed: [Tutorials]
# post has: categories: [News]

// after
plugins:
  - blog:
      categories_allowed: [Tutorials, News]

Defensive patterns

Strategy: validation

Validate before calling

import yaml, pathlib
allowed = set(cfg['plugins']['blog']['categories_allowed'])
for post in pathlib.Path('docs/posts').rglob('*.md'):
    meta = next(yaml.safe_load_all(post.read_text().split('---')[1:2])[0] for _ in [0]) if post.read_text().startswith('---') else {}
    for cat in (meta.get('categories') or []):
        assert cat in allowed, f"{post}: category '{cat}' not allowed"

Type guard

def is_allowed(name, allowed):
    return bool(allowed) and name in allowed

Try / catch

try:
    mkdocs.commands.build(config)
except PluginError as e:
    if "not in allow list" in str(e):
        log.error(f"Fix categories_allowed or the post metadata: {e}")
    raise

Prevention

Keep `categories_allowed` in sync whenever you add a new category to any post
Centralize category names in a shared list or lint script that checks posts against mkdocs.yml
Watch for case/typo differences between post metadata and mkdocs.yml

When it happens

Trigger: A post defines `categories: [something]` in its metadata while `plugins.blog.categories_allowed` in mkdocs.yml lists other names (or a typo'd name), and the blog plugin tries to generate the category view page for it.

Common situations: Adding a new category to posts without updating `categories_allowed`; typos or case mismatches between post metadata and mkdocs.yml; copying posts from another project with different allowed categories.

Related errors

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