Minor markdown improvements

README.md

@@ -31,6 +31,15 @@ crd-ref-docs \
     --renderer=markdown
 ```
 
+Additionally, a very basic MDX renderer is provided:
+
+```
+crd-ref-docs \
+    --source-path=$GOPATH/src/github.com/elastic/cloud-on-k8s/pkg/apis \
+    --config=config.yaml \
+    --renderer=mdx
+```
+
 Default templates are embedded in the binary. You may provide your own templates by specifying the templates directory:
 
 ```
@@ -42,7 +51,7 @@ crd-ref-docs \
 ```
 
 Default output mode writes all data to a single output file. 
-You can choose between single mode and group mode by specifying the output mode. 
+You can choose between single mode, group mode, or version mode by specifying the output mode. 
 In group mode, separate files are created for each API group, ensuring that the specified output path is an existing directory.
 ```
 crd-ref-docs \
@@ -51,6 +60,14 @@ crd-ref-docs \
     --output-path=./docs \
     --output-mode=group
 ```
+In version mode, separate files are created for each API group and version combination, ensuring that the specified output path is an existing directory.
+```
+crd-ref-docs \
+    --source-path=$GOPATH/src/github.com/elastic/cloud-on-k8s/pkg/apis \
+    --config=config.yaml \
+    --output-path=./docs \
+    --output-mode=version
+```
 
 ### Configuration
 

config/config.go

@@ -63,8 +63,9 @@ type KnownType struct {
 }
 
 const (
-	OutputModeSingle = "single"
-	OutputModeGroup  = "group"
+	OutputModeSingle       = "single"
+	OutputModeGroup        = "group"
+	OutputModeGroupVersion = "version"
 )
 
 type Flags struct {

renderer/markdown-x.go

@@ -0,0 +1,119 @@
+// Licensed to Elasticsearch B.V. under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Elasticsearch B.V. licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+package renderer
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"strings"
+	"text/template"
+
+	"github.com/Masterminds/sprig"
+	"github.com/elastic/crd-ref-docs/config"
+	"github.com/elastic/crd-ref-docs/templates"
+	"github.com/elastic/crd-ref-docs/types"
+)
+
+type MarkdownXRenderer struct {
+	*MarkdownRenderer
+}
+
+func NewMarkdownXRenderer(conf *config.Config) (*MarkdownXRenderer, error) {
+	markdownRenderer, err := NewMarkdownRenderer(conf)
+	if err != nil {
+		return nil, err
+	}
+	return &MarkdownXRenderer{markdownRenderer}, nil
+}
+
+func (m *MarkdownXRenderer) ToFuncMap() template.FuncMap {
+	fm := m.MarkdownRenderer.ToFuncMap()
+	fm["RenderLocalLink"] = m.RenderLocalLink
+	fm["RenderGVLink"] = m.RenderGVLink
+	fm["RenderTypeLink"] = m.RenderTypeLink
+	fm["RenderFieldDoc"] = m.RenderFieldDoc
+	return fm
+}
+
+func (m *MarkdownXRenderer) Render(gvd []types.GroupVersionDetails) error {
+	funcMap := combinedFuncMap(funcMap{prefix: "markdown", funcs: m.ToFuncMap()}, funcMap{funcs: sprig.TxtFuncMap()})
+
+	var tpls fs.FS
+	if m.conf.TemplatesDir != "" {
+		tpls = os.DirFS(m.conf.TemplatesDir)
+	} else {
+		sub, err := fs.Sub(templates.Root, "markdown-x")
+		if err != nil {
+			return err
+		}
+		tpls = sub
+	}
+
+	tmpl, err := loadTemplate(tpls, funcMap)
+	if err != nil {
+		return err
+	}
+
+	return renderTemplate(tmpl, m.conf, "mdx", gvd)
+}
+
+func (m *MarkdownXRenderer) RenderTypeLink(t *types.Type) string {
+	text := m.SimplifiedTypeName(t)
+
+	link, local := m.LinkForType(t)
+	if link == "" {
+		return text
+	}
+
+	if local {
+		return m.RenderLocalLink(text)
+	} else {
+		return m.RenderExternalLink(link, text)
+	}
+}
+
+func (m *MarkdownXRenderer) RenderLocalLink(text string) string {
+	anchor := strings.ToLower(
+		strings.NewReplacer(
+			" ", "-",
+			".", "",
+			"/", "",
+			"(", "",
+			")", "",
+		).Replace(text),
+	)
+
+	label := strings.NewReplacer("{", "\\{").Replace(text)
+
+	return fmt.Sprintf("[%s](#%s)", label, anchor)
+}
+
+func (m *MarkdownXRenderer) RenderGVLink(gv types.GroupVersionDetails) string {
+	return m.RenderLocalLink(gv.GroupVersionString())
+}
+
+func (m *MarkdownXRenderer) RenderFieldDoc(text string) string {
+	out := text
+
+	// escape inlined markup
+	out = strings.ReplaceAll(out, "<", "&lt;")
+	out = strings.ReplaceAll(out, ">", "&gt;")
+
+	// Pass to the inner renderer for further processing
+	return m.MarkdownRenderer.RenderFieldDoc(out)
+}

renderer/renderer.go

@@ -21,6 +21,7 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"strings"
 	"text/template"
 
 	"github.com/elastic/crd-ref-docs/config"
@@ -39,6 +40,8 @@ func New(conf *config.Config) (Renderer, error) {
 		return NewAsciidoctorRenderer(conf)
 	case "markdown":
 		return NewMarkdownRenderer(conf)
+	case "mdx":
+		return NewMarkdownXRenderer(conf)
 	default:
 		return nil, fmt.Errorf("unknown renderer: %s", conf.Renderer)
 	}
@@ -91,6 +94,24 @@ func renderTemplate(tmpl *template.Template, conf *config.Config, fileExtension
 				return err
 			}
 
+			if err := tmpl.ExecuteTemplate(file, mainTemplate, []types.GroupVersionDetails{gvd}); err != nil {
+				return err
+			}
+		}
+	case config.OutputModeGroupVersion:
+		for _, gvd := range gvds {
+			// To avoid filenames containing filepath separators, replace them with a non-separator value.
+			// Using the GroupVersionString is the core difference between this output mode and the regular
+			// group mode.
+			name := strings.NewReplacer("/", "-").Replace(gvd.GroupVersionString())
+
+			fileName := fmt.Sprintf("%s.%s", name, fileExtension)
+			file, err := createOutFile(conf.OutputPath, true, fileName)
+			defer file.Close()
+			if err != nil {
+				return err
+			}
+
 			if err := tmpl.ExecuteTemplate(file, mainTemplate, []types.GroupVersionDetails{gvd}); err != nil {
 				return err
 			}

templates/markdown-x/gv_details.tpl

@@ -0,0 +1,19 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+
+## {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if $gv.Kinds  }}
+### Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}

templates/markdown-x/gv_list.tpl

@@ -0,0 +1,19 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+<head>
+  <meta name="docsearch:indexPrefix" content="reference-doc" />
+</head>
+
+# API Reference
+
+## Packages
+{{- range $groupVersions }}
+- {{ markdownRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}

templates/markdown-x/type.tpl

@@ -0,0 +1,49 @@
+{{- define "type" -}}
+{{- $type := . -}}
+{{- if markdownShouldRenderType $type -}}
+
+### {{ $type.Name }}
+
+{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType  }}_{{ end }}
+
+{{ $type.Doc }}
+
+{{ if $type.Validation -}}
+_Validation:_
+{{- range $type.Validation }}
+- {{ . }}
+{{- end }}
+{{- end }}
+
+{{ if $type.References -}}
+_Appears in:_
+{{- range $type.SortedReferences }}
+- {{ markdownRenderTypeLink . }}
+{{- end }}
+{{- end }}
+
+{{ if $type.Members -}}
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+{{ if $type.GVK -}}
+| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | | |
+| `kind` _string_ | `{{ $type.GVK.Kind }}` | | |
+{{ end -}}
+
+{{ range $type.Members -}}
+| `{{ .Name  }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }} <br />{{ end }} |
+{{ end -}}
+
+{{ end -}}
+
+{{ if $type.EnumValues -}} 
+| Field | Description |
+| --- | --- |
+{{ range $type.EnumValues -}}
+| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
+{{ end -}}
+{{ end -}}
+
+
+{{- end -}}
+{{- end -}}

templates/markdown-x/type_members.tpl

@@ -0,0 +1,8 @@
+{{- define "type_members" -}}
+{{- $field := . -}}
+{{- if eq $field.Name "metadata" -}}
+Refer to Kubernetes API documentation for fields of `metadata`.
+{{- else -}}
+{{ markdownRenderFieldDoc $field.Doc }}
+{{- end -}}
+{{- end -}}

templates/templates.go

@@ -4,4 +4,5 @@ import "embed"
 
 //go:embed asciidoctor
 //go:embed markdown
+//go:embed markdown-x
 var Root embed.FS