diff --git a/src/markdoc/convertDocId.js b/src/markdoc/convertDocId.js
index 199e81a17..f5c6d4209 100644
--- a/src/markdoc/convertDocId.js
+++ b/src/markdoc/convertDocId.js
@@ -1,3 +1,7 @@
+import { readFileSync, existsSync } from 'fs'
+import * as path from 'path'
+import Markdoc from '@markdoc/markdoc'
+import yaml from 'js-yaml'
 import {
   nodeBottomNav,
   dcsBottomNav,
@@ -5,10 +9,37 @@ import {
   supportBottomNav,
 } from '@/markdoc/navigation.mjs'
 
+function getFrontmatter(filePath) {
+  const md = readFileSync(filePath, 'utf8')
+  const ast = Markdoc.parse(md)
+  const frontmatter = ast.attributes.frontmatter
+    ? yaml.load(ast.attributes.frontmatter)
+    : {}
+  return {
+    docId: frontmatter.docId,
+  }
+}
+
 export function convertDocId(href) {
+  if (href?.includes('docs.storj.io')) {
+    const url = new URL(href)
+    let dir = path.resolve('./app')
+    const filePath = path.join(dir, url.pathname, 'page.md')
+    if (
+      process.env.NODE_ENV !== 'production' ||
+      (url.host === new URL(process.env.SITE_URL).host && existsSync(filePath))
+    ) {
+      let { docId } = getFrontmatter(filePath)
+      throw new Error(
+        `Internal links should use the docId. replace ${href} with docId:${docId}`
+      )
+    }
+  }
+
   if (!href?.startsWith('docId')) {
     return { title: null, href }
   }
+
   let parts = href.split(':')
   let [docId, fragment] = parts[1].split('#')
   let entry = nodeBottomNav.find((o) => o.docId === docId)