squidfunk/mkdocs-material · error · PluginError

Couldn't resolve project URL: paths currently not supported

Error message

Couldn't resolve project URL: paths currently not supported
Please only use 'project://{url.hostname}'

What it means

Project references use the custom 'project://' URL scheme, and the plugin currently only supports the bare host form. When _resolve_project_url is given a URL that includes a path component (e.g. project://docs/sub), it raises PluginError explaining that paths are not supported yet and to use only project://hostname.

Source

Thrown at src/plugins/projects/plugin.py:266

                    project, url = self._resolve_project_url(url, config)

                    # Append file name if directory URLs are disabled
                    if not project.config.use_directory_urls:
                        url += "index.html"

                    # Replace link with project link
                    items[index] = ProjectLink(
                        item.title or project.config.site_name,
                        url
                    )

    # Resolve project URL and slug
    def _resolve_project_url(self, url: URL, config: MkDocsConfig):

        # Abort if the project URL contains a path, as we first need to collect
        # use cases for when, how and whether we need and want to support this
        if url.path != "":
            raise PluginError(
                f"Couldn't resolve project URL: paths currently not supported\n"
                f"Please only use 'project://{url.hostname}'"
            )

        # Compute slug from host name and convert to dot notation
        slug = url.hostname
        slug = slug if slug.startswith(".") else f".{slug}"

        # Resolve source and target project
        source: Project | None = None
        target: Project | None = None
        for ref, file in self.manifest.items():
            base = os.path.join(self.config.projects_root_dir, file)
            if file == os.path.relpath(
                config.config_file_path, self.config.projects_root_dir
            ):
                source = Project(base, self.config, ref)
            if slug == ref:

View on GitHub (pinned to e2136532f4)

Solutions

1. Remove the path portion and reference only the project root: project://hostname
2. Link to the specific subpage after the project resolution using the project's own relative path, or use the concrete published URL of the subpage
3. Track upstream mkdocs-material issues if you need path support in project:// URLs

Example fix

// before
[Subpage](project://my-docs/guide/setup)
// after
[Subpage](project://my-docs)

from urllib.parse import urlparse
u = urlparse(link)
if u.scheme == "project" and u.path:
    raise SystemExit(f"{link}: project:// supports hostname only")

def is_supported_project_url(url) -> bool:
    return url.scheme == "project" and url.path == ""

When it happens

Trigger: _replace encounters a link of the form project://hostname/some/path (url.path != "") while resolving inter-project references during the build.

Common situations: Authors naturally writing project://my-project/subpage expecting deep links into a sub-project; migrating existing absolute links to the project:// scheme without trimming the path; misunderstanding that only the project root can be referenced.

Related errors

• Aborted with {len(errors)} configuration errors
• Couldn't find project '{slug}'
• Relative path processor not registered
• Error reading filter configuration in '{key}': {e}
• Unknown shortcode: {type}

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