diff --git a/apps/documentation/src/components/MdxProvider/MdxTitle/MdxTitle.tsx b/apps/documentation/src/components/MdxProvider/MdxTitle/MdxTitle.tsx
index 0f5c040c..48adb3c7 100644
--- a/apps/documentation/src/components/MdxProvider/MdxTitle/MdxTitle.tsx
+++ b/apps/documentation/src/components/MdxProvider/MdxTitle/MdxTitle.tsx
@@ -2,40 +2,46 @@ import type { ElementType, JSX, ReactNode } from 'react'
 import { Title, type TitleProps } from '@mantine/core'
 
 export default function MdxTitle(props: TitleProps): JSX.Element {
+  const headingId = getIdFrom(props.children)
+
   return (
     <Title
-      data-heading={props.children}
+      data-heading={headingId}
       data-order={props.order}
       style={{ scrollMargin: 70 }}
       {...props}
-      id={idGen(props.children)}
+      id={headingId}
     />
   )
 }
 
-function idGen(children: ReactNode): string {
-  if (Array.isArray(children)) {
-    const result = children
-      .map((child) => {
-        if (typeof child === 'string') {
-          return child
-        }
-        if (typeof child === 'object' && child !== null && 'props' in child) {
-          const childWithProps = child as { props?: { children?: ReactNode } }
-          return typeof childWithProps.props?.children === 'string'
-            ? childWithProps.props.children
-            : ''
-        }
-        return ''
-      })
-      .join('')
-
-    return result.toLowerCase().replace(/\s+/g, '-')
+function getIdFrom(children: ReactNode): string {
+  const getTextContent = (node: ReactNode): string => {
+    if (typeof node === 'string') return node
+    if (typeof node === 'object' && node !== null && 'props' in node) {
+      const child = node as { props?: { children?: ReactNode } }
+      return getTextContent(child.props?.children)
+    }
+    return ''
   }
 
-  return typeof children === 'string'
-    ? children.toLowerCase().replace(/\s+/g, '-')
-    : ''
+  const textContent = Array.isArray(children)
+    ? children.map(getTextContent).join('')
+    : getTextContent(children)
+
+  return (
+    textContent
+      // normalize cause tuono build --static to hang
+      // @see https://github.com/tuono-labs/tuono/issues/468
+      // .normalize('NFKD')// separate accented characters into their base form and diacritical marks
+      .replace(/[\u0300-\u036f]/g, '') // remove all the accents
+      .trim()
+      .toLowerCase()
+      .replace(/\./g, '-') // some titles (configuration) contain keypath, so replace dots with hyphens
+      .replace(/[^a-z0-9 -]/g, '') // remove non-alphanumeric characters
+      .replace(/\s+/g, '-') // replace spaces with hyphens
+      .replace(/-+/g, '-') // remove consecutive hyphens
+  )
 }
 
 export const h = (order: 1 | 2 | 3 | 4 | 5 | 6): ElementType<TitleProps> => {
@@ -43,5 +49,6 @@ export const h = (order: 1 | 2 | 3 | 4 | 5 | 6): ElementType<TitleProps> => {
     return <MdxTitle order={order} {...props} />
   }
   render.displayName = 'H'
+
   return render
 }