diff --git a/hack/docgen/cli/gen.go b/hack/docgen/cli/gen.go
index 2111073b2..b6987ab77 100644
--- a/hack/docgen/cli/gen.go
+++ b/hack/docgen/cli/gen.go
@@ -153,9 +153,8 @@ func main() {
 				lines[idx] = ""
 				continue
 			}
-			if strings.Contains(line, ".md") && strings.Contains(line, "](") {
-				lines[idx] = strings.Replace(line, ".md", "", -1)
-			}
+			// Don't remove .md extensions - Docusaurus handles them properly
+			// and keeping them provides better IDE support and compatibility
 		}
 
 		newlines = append(newlines, lines...)
diff --git a/hack/docgen/def/mods/component.go b/hack/docgen/def/mods/component.go
index c27b8d4b9..20c21db8f 100644
--- a/hack/docgen/def/mods/component.go
+++ b/hack/docgen/def/mods/component.go
@@ -42,12 +42,12 @@ var ComponentDefDirs = []string{"./vela-templates/definitions/internal/component
 
 // CustomComponentHeaderEN .
 var CustomComponentHeaderEN = `---
-title: Built-in ParsedComponents Type
+title: Built-in Components Type
 ---
 
 This documentation will walk through all the built-in component types sorted alphabetically.
 
-` + fmt.Sprintf("> It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at %s.\n\n", time.Now().Format(time.RFC3339))
+` + fmt.Sprintf("> It was generated automatically by [scripts](../../contributor/cli-ref-doc.md), please don't update manually, last updated at %s.\n\n", time.Now().Format(time.RFC3339))
 
 // CustomComponentHeaderZH .
 var CustomComponentHeaderZH = `---
@@ -56,7 +56,7 @@ title: 内置组件列表
 
 本文档将**按字典序**展示所有内置组件的参数列表。
 
-` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339))
+` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc.md)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339))
 
 // ComponentDef generate component def reference doc
 func ComponentDef(ctx context.Context, c common.Args, opt Options) {
diff --git a/hack/docgen/def/mods/policy.go b/hack/docgen/def/mods/policy.go
index b18df2e8e..10d13ae65 100644
--- a/hack/docgen/def/mods/policy.go
+++ b/hack/docgen/def/mods/policy.go
@@ -47,7 +47,7 @@ title: Built-in Policy Type
 
 This documentation will walk through all the built-in policy types sorted alphabetically.
 
-` + fmt.Sprintf("> It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at %s.\n\n", time.Now().Format(time.RFC3339))
+` + fmt.Sprintf("> It was generated automatically by [scripts](../../contributor/cli-ref-doc.md), please don't update manually, last updated at %s.\n\n", time.Now().Format(time.RFC3339))
 
 // CustomPolicyHeaderZH .
 var CustomPolicyHeaderZH = `---
@@ -56,7 +56,7 @@ title: 内置策略列表
 
 本文档将**按字典序**展示所有内置策略的参数列表。
 
-` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339))
+` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc.md)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339))
 
 // PolicyDef generate policy def reference doc
 func PolicyDef(ctx context.Context, c common.Args, opt Options) {
diff --git a/hack/docgen/def/mods/trait.go b/hack/docgen/def/mods/trait.go
index 9376f84de..ed0ae9d35 100644
--- a/hack/docgen/def/mods/trait.go
+++ b/hack/docgen/def/mods/trait.go
@@ -47,7 +47,7 @@ title: Built-in Trait Type
 
 This documentation will walk through all the built-in trait types sorted alphabetically.
 
-` + fmt.Sprintf("> It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at %s.\n\n", time.Now().Format(time.RFC3339))
+` + fmt.Sprintf("> It was generated automatically by [scripts](../../contributor/cli-ref-doc.md), please don't update manually, last updated at %s.\n\n", time.Now().Format(time.RFC3339))
 
 // CustomTraitHeaderZH .
 var CustomTraitHeaderZH = `---
@@ -56,7 +56,7 @@ title: 内置运维特征列表
 
 本文档将**按字典序**展示所有内置运维特征的参数列表。
 
-` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339))
+` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc.md)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339))
 
 // TraitDef generate trait def reference doc
 func TraitDef(ctx context.Context, c common.Args, opt Options) {
diff --git a/hack/docgen/def/mods/workflow.go b/hack/docgen/def/mods/workflow.go
index 0d047b764..257abb1e6 100644
--- a/hack/docgen/def/mods/workflow.go
+++ b/hack/docgen/def/mods/workflow.go
@@ -47,7 +47,7 @@ title: Built-in WorkflowStep Type
 
 This documentation will walk through all the built-in workflow step types sorted alphabetically.
 
-` + fmt.Sprintf("> It was generated automatically by [scripts](../../contributor/cli-ref-doc), please don't update manually, last updated at %s.\n\n", time.Now().Format(time.RFC3339))
+` + fmt.Sprintf("> It was generated automatically by [scripts](../../contributor/cli-ref-doc.md), please don't update manually, last updated at %s.\n\n", time.Now().Format(time.RFC3339))
 
 // CustomWorkflowHeaderZH .
 var CustomWorkflowHeaderZH = `---
@@ -56,7 +56,7 @@ title: 内置工作流步骤列表
 
 本文档将**按字典序**展示所有内置工作流步骤的参数列表。
 
-` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339))
+` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc.md)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339))
 
 // WorkflowDef generate workflow def reference doc
 func WorkflowDef(ctx context.Context, c common.Args, opt Options) {
diff --git a/references/docgen/def-doc/trait/container-ports.eg.md b/references/docgen/def-doc/trait/container-ports.eg.md
index da00d019e..bd46218b9 100644
--- a/references/docgen/def-doc/trait/container-ports.eg.md
+++ b/references/docgen/def-doc/trait/container-ports.eg.md
@@ -1,5 +1,5 @@
 It's used to define Pod networks directly. hostPort routes the container's port directly to the port on the scheduled node, so that you can access the Pod through the host's IP plus hostPort.
-Don't specify a hostPort for a Pod unless it is absolutely necessary(run `DaemonSet` service). When you bind a Pod to a hostPort, it limits the number of places the Pod can be scheduled, because each <hostIP, hostPort, protocol> combination must be unique. If you don't specify the hostIP and protocol explicitly, Kubernetes will use 0.0.0.0 as the default hostIP and TCP as the default protocol.
+Don't specify a hostPort for a Pod unless it is absolutely necessary(run `DaemonSet` service). When you bind a Pod to a hostPort, it limits the number of places the Pod can be scheduled, because each `<hostIP, hostPort, protocol>` combination must be unique. If you don't specify the hostIP and protocol explicitly, Kubernetes will use 0.0.0.0 as the default hostIP and TCP as the default protocol.
 If you explicitly need to expose a Pod's port on the node, consider using `expose` or `gateway` trait, or exposeType and ports parameter of `webservice` component before resorting to `container-ports` trait.
 ```yaml
 apiVersion: core.oam.dev/v1beta1