{"record":{"id":"fb65fec1cdc23b70","repo":"squidfunk/mkdocs-material","slug":"couldn-t-resolve-project-url-paths-currently-not","errorCode":null,"errorMessage":"Couldn't resolve project URL: paths currently not supported\nPlease only use 'project://{url.hostname}'","messagePattern":"Couldn't resolve project URL: paths currently not supported\nPlease only use 'project://(.+?)'","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/projects/plugin.py","lineNumber":266,"sourceCode":"                    project, url = self._resolve_project_url(url, config)\n\n                    # Append file name if directory URLs are disabled\n                    if not project.config.use_directory_urls:\n                        url += \"index.html\"\n\n                    # Replace link with project link\n                    items[index] = ProjectLink(\n                        item.title or project.config.site_name,\n                        url\n                    )\n\n    # Resolve project URL and slug\n    def _resolve_project_url(self, url: URL, config: MkDocsConfig):\n\n        # Abort if the project URL contains a path, as we first need to collect\n        # use cases for when, how and whether we need and want to support this\n        if url.path != \"\":\n            raise PluginError(\n                f\"Couldn't resolve project URL: paths currently not supported\\n\"\n                f\"Please only use 'project://{url.hostname}'\"\n            )\n\n        # Compute slug from host name and convert to dot notation\n        slug = url.hostname\n        slug = slug if slug.startswith(\".\") else f\".{slug}\"\n\n        # Resolve source and target project\n        source: Project | None = None\n        target: Project | None = None\n        for ref, file in self.manifest.items():\n            base = os.path.join(self.config.projects_root_dir, file)\n            if file == os.path.relpath(\n                config.config_file_path, self.config.projects_root_dir\n            ):\n                source = Project(base, self.config, ref)\n            if slug == ref:","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/projects/plugin.py#L248-L284","documentation":"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.","triggerScenarios":"_replace encounters a link of the form project://hostname/some/path (url.path != \"\") while resolving inter-project references during the build.","commonSituations":"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.","solutions":["Remove the path portion and reference only the project root: project://hostname","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","Track upstream mkdocs-material issues if you need path support in project:// URLs"],"exampleFix":"// before\n[Subpage](project://my-docs/guide/setup)\n// after\n[Subpage](project://my-docs)","handlingStrategy":"validation","validationCode":"from urllib.parse import urlparse\nu = urlparse(link)\nif u.scheme == \"project\" and u.path:\n    raise SystemExit(f\"{link}: project:// supports hostname only\")","typeGuard":"def is_supported_project_url(url) -> bool:\n    return url.scheme == \"project\" and url.path == \"\"","tryCatchPattern":null,"preventionTips":["Only use project://hostname form in links; never append paths","Lint docs for project:// URLs containing '/' after the host","Document the limitation for contributors in the repo README"],"tags":["url","projects-plugin","mkdocs","unsupported-feature"],"backgroundTag":"unsupported-url-format","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}