diff --git a/packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/index.ts b/packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/index.ts
index 420caa67f7a4..0eeecb06a4d2 100644
--- a/packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/index.ts
+++ b/packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/index.ts
@@ -31,10 +31,6 @@ export type ResolveMarkdownLink = (
   params: ResolveMarkdownLinkParams,
 ) => string | null;
 
-// TODO: this plugin shouldn't be in the core MDX loader
-// After we allow plugins to provide Remark/Rehype plugins (see
-// https://github.com/facebook/docusaurus/issues/6370), this should be provided
-// by theme-mermaid itself
 export interface PluginOptions {
   resolveMarkdownLink: ResolveMarkdownLink;
 }
diff --git a/packages/docusaurus-plugin-content-docs/src/versions/index.ts b/packages/docusaurus-plugin-content-docs/src/versions/index.ts
index 87eb16cab5f5..bb77f8cbbdf4 100644
--- a/packages/docusaurus-plugin-content-docs/src/versions/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/versions/index.ts
@@ -278,10 +278,6 @@ export function getVersionFromSourceFilePath(
       filePath.startsWith(docsDirPath),
     ),
   );
-  // At this point, this should never happen, because the MDX loaders' paths are
-  // literally using the version content paths; but if we allow sourcing content
-  // from outside the docs directory (through the `include` option, for example;
-  // is there a compelling use-case?), this would actually be testable
   if (!versionFound) {
     throw new Error(
       `Unexpected error: file at "${filePath}" does not belong to any docs version!`,
diff --git a/packages/docusaurus-utils/src/markdownLinks.ts b/packages/docusaurus-utils/src/markdownLinks.ts
index 265cf28ba200..1b65776187f8 100644
--- a/packages/docusaurus-utils/src/markdownLinks.ts
+++ b/packages/docusaurus-utils/src/markdownLinks.ts
@@ -40,6 +40,9 @@ export type BrokenMarkdownLink<T extends ContentPaths> = {
   link: string;
 };
 
+// Note this is historical logic extracted during a 2024 refactor
+// The algo has been kept exactly as before for retro compatibility
+// See also https://github.com/facebook/docusaurus/pull/10168
 export function resolveMarkdownLinkPathname(
   linkPathname: string,
   context: {