diff --git a/lib/callout-directive.js b/lib/callout-directive.js
new file mode 100644
index 0000000..4837943
--- /dev/null
+++ b/lib/callout-directive.js
@@ -0,0 +1,41 @@
+import { visit } from 'unist-util-visit';
+
+export default function calloutDirective() {
+  return (tree) => {
+    visit(tree, (node) => {
+      // Handle textDirective (has content) and leafDirective (no content)
+      if (node.type === 'textDirective' || node.type === 'leafDirective') {
+        const name = node.name;
+
+        // Only handle known callout types
+        const validTypes = ['note', 'tip', 'warning', 'danger'];
+        if (!validTypes.includes(name)) return;
+
+        // Extract attributes (e.g., title="...")
+        const attributes = node.attributes || [];
+        const attrs = attributes.map((attr) => ({
+          type: 'mdxJsxAttribute',
+          name: attr.name,
+          value: attr.value,
+        }));
+
+        // Add type attribute
+        attrs.push({
+          type: 'mdxJsxAttribute',
+          name: 'type',
+          value: { type: 'mdxFlowExpression', value: `"${name}"` },
+        });
+
+        // Build children from node's children
+        const children = node.children || [];
+
+        // Transform to mdxJsxFlowElement
+        node.type = 'mdxJsxFlowElement';
+        node.name = 'Callout';
+        node.attributes = attrs;
+        node.children = children;
+        node.data = { hName: 'Callout', hProperties: {} };
+      }
+    });
+  };
+}
diff --git a/next.config.ts b/next.config.ts
index 6aa9861..8bbb3e2 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -2,6 +2,7 @@ import type { NextConfig } from 'next'
 import createMDX from '@next/mdx'
 
 const mdxCodeBlockPipeline = new URL('./lib/mdx-hast-visitor.js', import.meta.url).pathname
+const calloutDirectivePath = new URL('./lib/callout-directive.js', import.meta.url).pathname
 
 const nextConfig: NextConfig = {
   output: 'export',
@@ -11,7 +12,14 @@ const nextConfig: NextConfig = {
 
 const withMDX = createMDX({
   options: {
-    remarkPlugins: ['remark-frontmatter', 'remark-smartypants', 'remark-math', 'remark-gfm'],
+    remarkPlugins: [
+      'remark-frontmatter',
+      'remark-smartypants',
+      'remark-math',
+      'remark-gfm',
+      'remark-directive',
+      calloutDirectivePath,
+    ],
     rehypePlugins: [
       'rehype-slug',
       ['rehype-external-links', { target: '_blank', rel: ['nofollow', 'noopener', 'noreferrer'] }],
diff --git a/package.json b/package.json
index 3c7c084..c57e36c 100644
--- a/package.json
+++ b/package.json
@@ -20,12 +20,13 @@
     "next": "16.2.6",
     "react": "19.2.4",
     "react-dom": "19.2.4",
-    "remark-frontmatter": "^5.0.0",
     "rehype-autolink-headings": "^7.1.0",
     "rehype-external-links": "^3.0.0",
     "rehype-katex": "^7.0.1",
     "rehype-pretty-code": "^0.14.3",
     "rehype-slug": "^6.0.0",
+    "remark-directive": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
     "remark-smartypants": "^3.0.2"