docs: formatting updates to api reference

site/crd-ref-docs/config.yaml

@@ -34,3 +34,7 @@ render:
     - name: ExtProc
       package: github.com/envoyproxy/gateway/api/v1alpha1
       link: https://gateway.envoyproxy.io/docs/api/extension_types/#extproc
+
+navigation:
+  includeTOC: true
+  includeBackToTopLinks: true

site/crd-ref-docs/templates/gv_details.tpl

@@ -1,19 +1,22 @@
 {{- define "gvDetails" -}}
 {{- $gv := . -}}
 
-## {{ $gv.GroupVersionString }}
+<a name="{{ lower (replace $gv.GroupVersionString " " "-" ) }}"></a>
+# {{ $gv.GroupVersionString }}
 
 {{ $gv.Doc }}
 
 {{- if $gv.Kinds  }}
-### Resource Types
+## Resource Types
 {{- range $gv.SortedKinds }}
-- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
+- {{ markdownRenderTypeLink ($gv.TypeForKind .) }}
 {{- end }}
 {{ end }}
 
 {{ range $gv.SortedTypes }}
 {{ template "type" . }}
 {{ end }}
 
+[Back to Packages](#api_references)
+
 {{- end -}}

site/crd-ref-docs/templates/gv_list.tpl

@@ -1,15 +1,15 @@
 {{- define "gvList" -}}
 {{- $groupVersions := . -}}
 
-
 ---
 id: api_references
 title: API Reference
 ---
 
-## Packages
+<a id="api_references"></a>
+# Packages
 {{- range $groupVersions }}
-- {{ markdownRenderGVLink . }}
+- [{{ .GroupVersionString }}](#{{ lower (replace .GroupVersionString " " "-" ) }})
 {{- end }}
 
 {{ range $groupVersions }}

site/crd-ref-docs/templates/type.tpl

@@ -2,7 +2,7 @@
 {{- $type := . -}}
 {{- if markdownShouldRenderType $type -}}
 
-#### {{ $type.Name }}
+### {{ $type.Name }}
 
 {{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType  }}_{{ end }}
 
@@ -16,26 +16,34 @@ _Appears in:_
 {{- end }}
 
 {{ if $type.Members -}}
-| Field | Type | Required | Description |
-| ---   | ---  | ---      | ---         |
 {{ if $type.GVK -}}
-| `apiVersion` | _string_ | |`{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
-| `kind` | _string_ | |`{{ $type.GVK.Kind }}`
+- **apiVersion**
+  - **Type:** _string_
+  - **Value:** `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
+- **kind**
+  - **Type:** _string_
+  - **Value:** `{{ $type.GVK.Kind }}`
 {{ end -}}
-
 {{ range $type.Members -}}
 {{- with .Markers.notImplementedHide -}}
 {{- else -}}
-| `{{ .Name  }}` | _{{ markdownRenderType .Type }}_ | {{ with .Markers.optional }} {{ "false" }} {{ else }} {{ "true" }} {{end}} | {{ template "type_members" . }} |
+- **{{ .Name }}**
+  - **Type:** _{{ markdownRenderType .Type }}_
+  - **Required:** {{ if .Markers.optional }}No{{ else }}Yes{{ end }}
+  {{- if .Doc }}
+  - **Description:** {{ .Doc }}
+  {{- end }}
 {{ end -}}
 {{- end -}}
 {{- end -}}
+
 {{ if $type.EnumValues -}}
 | Value | Description |
 | ----- | ----------- |
 {{ range $type.EnumValues -}}
 | `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
 {{ end -}}
 {{- end -}}
+
 {{- end -}}
 {{- end -}}