Skip to content

Commit b2bfbbc

Browse files
admacleodadmacleod
committed
Add an mdx renderer
1 parent 8b3fd1c commit b2bfbbc

8 files changed

Lines changed: 226 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,15 @@ crd-ref-docs \
3131
--renderer=markdown
3232
```
3333

34+
Additionally, a very basic MDX renderer is provided:
35+
36+
```
37+
crd-ref-docs \
38+
--source-path=$GOPATH/src/github.com/elastic/cloud-on-k8s/pkg/apis \
39+
--config=config.yaml \
40+
--renderer=mdx
41+
```
42+
3443
Default templates are embedded in the binary. You may provide your own templates by specifying the templates directory:
3544

3645
```

‎renderer/markdown-x.go‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
// Licensed to Elasticsearch B.V. under one or more contributor
2+
// license agreements. See the NOTICE file distributed with
3+
// this work for additional information regarding copyright
4+
// ownership. Elasticsearch B.V. licenses this file to you under
5+
// the Apache License, Version 2.0 (the "License"); you may
6+
// not use this file except in compliance with the License.
7+
// You may obtain a copy of the License at
8+
//
9+
// http://www.apache.org/licenses/LICENSE-2.0
10+
//
11+
// Unless required by applicable law or agreed to in writing,
12+
// software distributed under the License is distributed on an
13+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
// KIND, either express or implied. See the License for the
15+
// specific language governing permissions and limitations
16+
// under the License.
17+
package renderer
18+
19+
import (
20+
"fmt"
21+
"io/fs"
22+
"os"
23+
"strings"
24+
"text/template"
25+
26+
"github.com/Masterminds/sprig"
27+
"github.com/elastic/crd-ref-docs/config"
28+
"github.com/elastic/crd-ref-docs/templates"
29+
"github.com/elastic/crd-ref-docs/types"
30+
)
31+
32+
type MarkdownXRenderer struct {
33+
*MarkdownRenderer
34+
}
35+
36+
func NewMarkdownXRenderer(conf *config.Config) (*MarkdownXRenderer, error) {
37+
markdownRenderer, err := NewMarkdownRenderer(conf)
38+
if err != nil {
39+
return nil, err
40+
}
41+
return &MarkdownXRenderer{markdownRenderer}, nil
42+
}
43+
44+
func (m *MarkdownXRenderer) ToFuncMap() template.FuncMap {
45+
fm := m.MarkdownRenderer.ToFuncMap()
46+
fm["RenderLocalLink"] = m.RenderLocalLink
47+
fm["RenderGVLink"] = m.RenderGVLink
48+
fm["RenderTypeLink"] = m.RenderTypeLink
49+
fm["RenderFieldDoc"] = m.RenderFieldDoc
50+
return fm
51+
}
52+
53+
func (m *MarkdownXRenderer) Render(gvd []types.GroupVersionDetails) error {
54+
funcMap := combinedFuncMap(funcMap{prefix: "markdown", funcs: m.ToFuncMap()}, funcMap{funcs: sprig.TxtFuncMap()})
55+
56+
var tpls fs.FS
57+
if m.conf.TemplatesDir != "" {
58+
tpls = os.DirFS(m.conf.TemplatesDir)
59+
} else {
60+
sub, err := fs.Sub(templates.Root, "markdown-x")
61+
if err != nil {
62+
return err
63+
}
64+
tpls = sub
65+
}
66+
67+
tmpl, err := loadTemplate(tpls, funcMap)
68+
if err != nil {
69+
return err
70+
}
71+
72+
return renderTemplate(tmpl, m.conf, "mdx", gvd)
73+
}
74+
75+
func (m *MarkdownXRenderer) RenderTypeLink(t *types.Type) string {
76+
text := m.SimplifiedTypeName(t)
77+
78+
link, local := m.LinkForType(t)
79+
if link == "" {
80+
return text
81+
}
82+
83+
if local {
84+
return m.RenderLocalLink(text)
85+
} else {
86+
return m.RenderExternalLink(link, text)
87+
}
88+
}
89+
90+
func (m *MarkdownXRenderer) RenderLocalLink(text string) string {
91+
anchor := strings.ToLower(
92+
strings.NewReplacer(
93+
" ", "-",
94+
".", "",
95+
"/", "",
96+
"(", "",
97+
")", "",
98+
).Replace(text),
99+
)
100+
101+
label := strings.NewReplacer("{", "\\{").Replace(text)
102+
103+
return fmt.Sprintf("[%s](#%s)", label, anchor)
104+
}
105+
106+
func (m *MarkdownXRenderer) RenderGVLink(gv types.GroupVersionDetails) string {
107+
return m.RenderLocalLink(gv.GroupVersionString())
108+
}
109+
110+
func (m *MarkdownXRenderer) RenderFieldDoc(text string) string {
111+
out := text
112+
113+
// escape inlined markup
114+
out = strings.ReplaceAll(out, "<", "&lt;")
115+
out = strings.ReplaceAll(out, ">", "&gt;")
116+
117+
// Pass to the inner renderer for further processing
118+
return m.MarkdownRenderer.RenderFieldDoc(out)
119+
}

‎renderer/renderer.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@ func New(conf *config.Config) (Renderer, error) {
4040
return NewAsciidoctorRenderer(conf)
4141
case "markdown":
4242
return NewMarkdownRenderer(conf)
43+
case "mdx":
44+
return NewMarkdownXRenderer(conf)
4345
default:
4446
return nil, fmt.Errorf("unknown renderer: %s", conf.Renderer)
4547
}

‎templates/markdown-x/gv_details.tpl‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{{- define "gvDetails" -}}
2+
{{- $gv := . -}}
3+
4+
## {{ $gv.GroupVersionString }}
5+
6+
{{ $gv.Doc }}
7+
8+
{{- if $gv.Kinds }}
9+
### Resource Types
10+
{{- range $gv.SortedKinds }}
11+
- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
12+
{{- end }}
13+
{{ end }}
14+
15+
{{ range $gv.SortedTypes }}
16+
{{ template "type" . }}
17+
{{ end }}
18+
19+
{{- end -}}

‎templates/markdown-x/gv_list.tpl‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{{- define "gvList" -}}
2+
{{- $groupVersions := . -}}
3+
4+
<head>
5+
<meta name="docsearch:indexPrefix" content="reference-doc" />
6+
</head>
7+
8+
# API Reference
9+
10+
## Packages
11+
{{- range $groupVersions }}
12+
- {{ markdownRenderGVLink . }}
13+
{{- end }}
14+
15+
{{ range $groupVersions }}
16+
{{ template "gvDetails" . }}
17+
{{ end }}
18+
19+
{{- end -}}

‎templates/markdown-x/type.tpl‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
{{- define "type" -}}
2+
{{- $type := . -}}
3+
{{- if markdownShouldRenderType $type -}}
4+
5+
### {{ $type.Name }}
6+
7+
{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType }}_{{ end }}
8+
9+
{{ $type.Doc }}
10+
11+
{{ if $type.Validation -}}
12+
_Validation:_
13+
{{- range $type.Validation }}
14+
- {{ . }}
15+
{{- end }}
16+
{{- end }}
17+
18+
{{ if $type.References -}}
19+
_Appears in:_
20+
{{- range $type.SortedReferences }}
21+
- {{ markdownRenderTypeLink . }}
22+
{{- end }}
23+
{{- end }}
24+
25+
{{ if $type.Members -}}
26+
| Field | Description | Default | Validation |
27+
| --- | --- | --- | --- |
28+
{{ if $type.GVK -}}
29+
| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | | |
30+
| `kind` _string_ | `{{ $type.GVK.Kind }}` | | |
31+
{{ end -}}
32+
33+
{{ range $type.Members -}}
34+
| `{{ .Name }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }} <br />{{ end }} |
35+
{{ end -}}
36+
37+
{{ end -}}
38+
39+
{{ if $type.EnumValues -}}
40+
| Field | Description |
41+
| --- | --- |
42+
{{ range $type.EnumValues -}}
43+
| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
44+
{{ end -}}
45+
{{ end -}}
46+
47+
48+
{{- end -}}
49+
{{- end -}}

‎templates/markdown-x/type_members.tpl‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{{- define "type_members" -}}
2+
{{- $field := . -}}
3+
{{- if eq $field.Name "metadata" -}}
4+
Refer to Kubernetes API documentation for fields of `metadata`.
5+
{{- else -}}
6+
{{ markdownRenderFieldDoc $field.Doc }}
7+
{{- end -}}
8+
{{- end -}}

‎templates/templates.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@ import "embed"
44

55
//go:embed asciidoctor
66
//go:embed markdown
7+
//go:embed markdown-x
78
var Root embed.FS

0 commit comments

Comments
 (0)