Skip to content

Commit f40ed68

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

8 files changed

Lines changed: 180 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: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
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+
"io/fs"
21+
"os"
22+
"strings"
23+
24+
"github.com/Masterminds/sprig"
25+
"github.com/elastic/crd-ref-docs/config"
26+
"github.com/elastic/crd-ref-docs/templates"
27+
"github.com/elastic/crd-ref-docs/types"
28+
)
29+
30+
type MarkdownXRenderer struct {
31+
*MarkdownRenderer
32+
}
33+
34+
func NewMarkdownXRenderer(conf *config.Config) (*MarkdownXRenderer, error) {
35+
markdownRenderer, err := NewMarkdownRenderer(conf)
36+
if err != nil {
37+
return nil, err
38+
}
39+
return &MarkdownXRenderer{markdownRenderer}, nil
40+
}
41+
42+
func (m *MarkdownXRenderer) Render(gvd []types.GroupVersionDetails) error {
43+
funcMap := combinedFuncMap(funcMap{prefix: "markdown", funcs: m.ToFuncMap()}, funcMap{funcs: sprig.TxtFuncMap()})
44+
45+
var tpls fs.FS
46+
if m.conf.TemplatesDir != "" {
47+
tpls = os.DirFS(m.conf.TemplatesDir)
48+
} else {
49+
sub, err := fs.Sub(templates.Root, "markdown-x")
50+
if err != nil {
51+
return err
52+
}
53+
tpls = sub
54+
}
55+
56+
tmpl, err := loadTemplate(tpls, funcMap)
57+
if err != nil {
58+
return err
59+
}
60+
61+
return renderTemplate(tmpl, m.conf, "mdx", gvd)
62+
}
63+
64+
func (m *MarkdownXRenderer) RenderFieldDoc(text string) string {
65+
out := text
66+
67+
// escape inlined markup
68+
out = strings.ReplaceAll(out, "<", "&lt;")
69+
out = strings.ReplaceAll(out, ">", "&gt;")
70+
71+
// Pass to the inner renderer for further processing
72+
return m.MarkdownRenderer.RenderFieldDoc(out)
73+
}

‎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)