elastic · pebrc · Mar 3, 2025 · Feb 28, 2025 · Feb 28, 2025 · Feb 28, 2025
diff --git a/docs/docset.yml b/docs/docset.yml
diff --git a/docs/reference/api-docs.asciidoc b/docs/reference/api-docs.asciidoc
diff --git a/docs/reference/api-docs.md b/docs/reference/api-docs.md
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -0,0 +1,13 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-reference.html
+applies_to:
+  deployment:
+    eck: all
+---
+
+# Elastic Cloud on Kubernetes [k8s-reference]
+
+This section contains reference information for {{eck}}, including:
+
+* [API Reference](./api-docs.md)
diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml
@@ -0,0 +1,3 @@
+toc:
+  - file: index.md
+  - file: api-docs.md
diff --git a/hack/api-docs/build.sh b/hack/api-docs/build.sh
@@ -37,9 +37,9 @@ build_docs() {
         echo "Generating API reference documentation"
         "${BIN_DIR}"/crd-ref-docs --source-path="${REPO_ROOT}"/pkg/apis \
             --config="${SCRIPT_DIR}"/config.yaml \
-            --renderer=asciidoctor \
+            --renderer=markdown \
             --templates-dir="${SCRIPT_DIR}"/templates \
-            --output-path="${DOCS_DIR}"/reference/api-docs.asciidoc
+            --output-path="${DOCS_DIR}"/reference/api-docs.md
     )
 }
 

diff --git a/hack/api-docs/templates/gv_details.tpl b/hack/api-docs/templates/gv_details.tpl
@@ -1,14 +1,15 @@
 {{- define "gvDetails" -}}
 {{- $gv := . -}}
-[id="{{ asciidocGroupVersionID $gv | asciidocRenderAnchorID }}"]
-== {{ $gv.GroupVersionString }}
+
+% TODO add function to crd-ref-docs return anchor used in links docs-v3 does not seem to produce valid markdown anchors
+## {{ $gv.GroupVersionString }} [#{{ markdownGroupVersionID $gv | replace "-" "" }}]
 
 {{ $gv.Doc }}
 
 {{- if $gv.Kinds  }}
-.Resource Types
+### Resource Types
 {{- range $gv.SortedKinds }}
-- {{ $gv.TypeForKind . | asciidocRenderTypeLink }}
+- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
 {{- end }}
 {{ end }}
 

diff --git a/hack/api-docs/templates/gv_list.tpl b/hack/api-docs/templates/gv_list.tpl
@@ -1,22 +1,20 @@
 {{- define "gvList" -}}
 {{- $groupVersions := . -}}
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-api-reference.html
+navigation_title: API Reference
+applies_to:
+  deployment:
+    eck: all
+---
+% Generated documentation. Please do not edit.
 
-// Generated documentation. Please do not edit.
-:page_id: api-reference
-:anchor_prefix: k8s-api
+# {{`{{eck}}`}} API Reference [k8s-api-reference]
 
-ifdef::env-github[]
-****
-link:https://www.elastic.co/guide/en/cloud-on-k8s/master/k8s-{page_id}.html[View this document on the Elastic website]
-****
-endif::[]
-
-[id="{p}-{page_id}"]
-= API Reference
-
-.Packages
+## Packages
 {{- range $groupVersions }}
-- {{ asciidocRenderGVLink . }}
+* {{ markdownRenderGVLink . }}
 {{- end }}
 
 {{ range $groupVersions }}

diff --git a/hack/api-docs/templates/type.tpl b/hack/api-docs/templates/type.tpl
@@ -1,34 +1,31 @@
 {{- define "type" -}}
 {{- $type := . -}}
-{{- if asciidocShouldRenderType $type -}}
+{{- if markdownShouldRenderType $type -}}
 
-[id="{{ asciidocTypeID $type | asciidocRenderAnchorID }}"]
-=== {{ $type.Name  }} {{ if $type.IsAlias }}({{ asciidocRenderTypeLink $type.UnderlyingType  }}) {{ end }}
+### {{ $type.Name  }} {{ if $type.IsAlias }}({{ markdownRenderTypeLink $type.UnderlyingType  }}) {{ end }} [#{{ $type.Name | lower }}]
 
 {{ $type.Doc }}
 
 {{ if $type.References -}}
-.Appears In:
-****
+:::{admonition} Appears In:
 {{- range $type.SortedReferences }}
-- {{ asciidocRenderTypeLink . }}
+* {{ markdownRenderTypeLink . }}
 {{- end }}
-****
+
+:::
 {{- end }}
 
 {{ if $type.Members -}}
-[cols="25a,75a", options="header"]
-|===
-| Field | Description
+| Field | Description |
+| --- | --- |
 {{ if $type.GVK -}}
-| *`apiVersion`* __string__ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
-| *`kind`* __string__ | `{{ $type.GVK.Kind }}`
+| *`apiVersion`* __string__ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` |
+| *`kind`* __string__ | `{{ $type.GVK.Kind }}` | 
 {{ end -}}
 
 {{ range $type.Members -}}
-| *`{{ .Name  }}`* __{{ asciidocRenderType .Type }}__ | {{ template "type_members" . }}
+| *`{{ .Name  }}`* __{{ markdownRenderType .Type }}__ | {{ template "type_members" . }} |
 {{ end -}}
-|===
 {{ end -}}
 
 {{- end -}}

diff --git a/hack/api-docs/templates/type_members.tpl b/hack/api-docs/templates/type_members.tpl
@@ -2,7 +2,7 @@
 {{- $field := . -}}
 {{- if eq $field.Name "metadata" -}}
 Refer to Kubernetes API documentation for fields of `metadata`.
-{{ else -}}
-{{ $field.Doc }}
+{{- else -}}
+{{ $field.Doc | replace "\n" "<br>" }}
 {{- end -}}
 {{- end -}}