Skip to content

Commit 4e5d193

Browse files
antonincmsantonincms
committed
Fix markdown links to multi-version CRDs
This change will break existing links in custom Markdown templates, as it now uses GroupVersionID to link to resources. To fix this, replace `## {{ $gv.GroupVersionString }}` in gv_details.tpl with `## <a id="{{ markdownGroupVersionID $gv | markdownSafeID }}">{{ $gv.GroupVersionString }}</a>`.
1 parent c85b7b3 commit 4e5d193

7 files changed

Lines changed: 103 additions & 112 deletions

File tree

‎renderer/markdown.go‎

Lines changed: 4 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -114,23 +114,14 @@ func (m *MarkdownRenderer) RenderTypeLink(t *types.Type) string {
114114
}
115115

116116
if local {
117-
return m.RenderLocalLink(text)
117+
return m.RenderLocalLink(link, text)
118118
} else {
119119
return m.RenderExternalLink(link, text)
120120
}
121121
}
122122

123-
func (m *MarkdownRenderer) RenderLocalLink(text string) string {
124-
anchor := strings.ToLower(
125-
strings.NewReplacer(
126-
" ", "-",
127-
".", "",
128-
"/", "",
129-
"(", "",
130-
")", "",
131-
).Replace(text),
132-
)
133-
return fmt.Sprintf("[%s](#%s)", text, anchor)
123+
func (m *MarkdownRenderer) RenderLocalLink(link, text string) string {
124+
return fmt.Sprintf("[%s](#%s)", text, link)
134125
}
135126

136127
func (m *MarkdownRenderer) TemplateValue(key string) string {
@@ -145,7 +136,7 @@ func (m *MarkdownRenderer) RenderExternalLink(link, text string) string {
145136
}
146137

147138
func (m *MarkdownRenderer) RenderGVLink(gv types.GroupVersionDetails) string {
148-
return m.RenderLocalLink(gv.GroupVersionString())
139+
return m.RenderLocalLink(m.GroupVersionID(gv), gv.GroupVersionString())
149140
}
150141

151142
func (m *MarkdownRenderer) RenderFieldDoc(text string) string {

‎templates/markdown/gv_details.tpl‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{{- define "gvDetails" -}}
22
{{- $gv := . -}}
33

4-
## {{ $gv.GroupVersionString }}
4+
## <a id="{{ markdownGroupVersionID $gv | markdownSafeID }}">{{ $gv.GroupVersionString }}</a>
55

66
{{ $gv.Doc }}
77

‎templates/markdown/type.tpl‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
{{- $type := . -}}
33
{{- if markdownShouldRenderType $type -}}
44

5-
#### {{ $type.Name }}
5+
#### <a id="{{ markdownTypeID $type | markdownSafeID }}">{{ $type.Name }}</a>
66

77
{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType }}_{{ end }}
88

@@ -36,7 +36,7 @@ _Appears in:_
3636

3737
{{ end -}}
3838

39-
{{ if $type.EnumValues -}}
39+
{{ if $type.EnumValues -}}
4040
| Field | Description |
4141
| --- | --- |
4242
{{ range $type.EnumValues -}}

‎test/expected.md‎

Lines changed: 47 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
# API Reference
22

33
## Packages
4-
- [webapp.test.k8s.elastic.co/common](#webapptestk8selasticcocommon)
5-
- [webapp.test.k8s.elastic.co/v1](#webapptestk8selasticcov1)
4+
- [webapp.test.k8s.elastic.co/common](#webapp-test-k8s-elastic-co-common)
5+
- [webapp.test.k8s.elastic.co/v1](#webapp-test-k8s-elastic-co-v1)
66

77

8-
## webapp.test.k8s.elastic.co/common
8+
## <a id="webapp-test-k8s-elastic-co-common">webapp.test.k8s.elastic.co/common</a>
99

1010
Package common contains common API Schema definitions
1111

1212

1313

14-
#### CommonString
14+
#### <a id="github-com-elastic-crd-ref-docs-api-common-commonstring">CommonString</a>
1515

1616
_Underlying type:_ _string_
1717

@@ -20,25 +20,25 @@ _Underlying type:_ _string_
2020

2121

2222
_Appears in:_
23-
- [GuestbookSpec](#guestbookspec)
24-
- [GuestbookStatus](#guestbookstatus)
23+
- [GuestbookSpec](#github-com-elastic-crd-ref-docs-api-v1-guestbookspec)
24+
- [GuestbookStatus](#github-com-elastic-crd-ref-docs-api-v1-guestbookstatus)
2525

2626

2727

2828

29-
## webapp.test.k8s.elastic.co/v1
29+
## <a id="webapp-test-k8s-elastic-co-v1">webapp.test.k8s.elastic.co/v1</a>
3030

3131
Package v1 contains API Schema definitions for the webapp v1 API group
3232

3333
### Resource Types
34-
- [Embedded](#embedded)
35-
- [Guestbook](#guestbook)
36-
- [GuestbookList](#guestbooklist)
37-
- [Underlying](#underlying)
34+
- [Embedded](#github-com-elastic-crd-ref-docs-api-v1-embedded)
35+
- [Guestbook](#github-com-elastic-crd-ref-docs-api-v1-guestbook)
36+
- [GuestbookList](#github-com-elastic-crd-ref-docs-api-v1-guestbooklist)
37+
- [Underlying](#github-com-elastic-crd-ref-docs-api-v1-underlying)
3838

3939

4040

41-
#### Embedded
41+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-embedded">Embedded</a>
4242

4343

4444

@@ -59,7 +59,7 @@ Package v1 contains API Schema definitions for the webapp v1 API group
5959
| `value` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#json-v1-apiextensions-k8s-io)_ | | | |
6060

6161

62-
#### Embedded1
62+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-embedded1">Embedded1</a>
6363

6464

6565

@@ -68,7 +68,7 @@ Package v1 contains API Schema definitions for the webapp v1 API group
6868

6969

7070
_Appears in:_
71-
- [Embedded](#embedded)
71+
- [Embedded](#github-com-elastic-crd-ref-docs-api-v1-embedded)
7272

7373
| Field | Description | Default | Validation |
7474
| --- | --- | --- | --- |
@@ -77,7 +77,7 @@ _Appears in:_
7777
| `value` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#json-v1-apiextensions-k8s-io)_ | | | |
7878

7979

80-
#### EmbeddedX
80+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-embeddedx">EmbeddedX</a>
8181

8282

8383

@@ -86,16 +86,16 @@ _Appears in:_
8686

8787

8888
_Appears in:_
89-
- [Embedded](#embedded)
90-
- [Embedded1](#embedded1)
89+
- [Embedded](#github-com-elastic-crd-ref-docs-api-v1-embedded)
90+
- [Embedded1](#github-com-elastic-crd-ref-docs-api-v1-embedded1)
9191

9292
| Field | Description | Default | Validation |
9393
| --- | --- | --- | --- |
9494
| `x` _string_ | | | |
9595
| `value` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#json-v1-apiextensions-k8s-io)_ | | | |
9696

9797

98-
#### Guestbook
98+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-guestbook">Guestbook</a>
9999

100100

101101

@@ -104,17 +104,17 @@ Guestbook is the Schema for the guestbooks API.
104104

105105

106106
_Appears in:_
107-
- [GuestbookList](#guestbooklist)
107+
- [GuestbookList](#github-com-elastic-crd-ref-docs-api-v1-guestbooklist)
108108

109109
| Field | Description | Default | Validation |
110110
| --- | --- | --- | --- |
111111
| `apiVersion` _string_ | `webapp.test.k8s.elastic.co/v1` | | |
112112
| `kind` _string_ | `Guestbook` | | |
113113
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
114-
| `spec` _[GuestbookSpec](#guestbookspec)_ | | \{ page:1 \} | |
114+
| `spec` _[GuestbookSpec](#github-com-elastic-crd-ref-docs-api-v1-guestbookspec)_ | | \{ page:1 \} | |
115115

116116

117-
#### GuestbookEntry
117+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-guestbookentry">GuestbookEntry</a>
118118

119119

120120

@@ -123,22 +123,22 @@ GuestbookEntry defines an entry in a guest book.
123123

124124

125125
_Appears in:_
126-
- [GuestbookSpec](#guestbookspec)
126+
- [GuestbookSpec](#github-com-elastic-crd-ref-docs-api-v1-guestbookspec)
127127

128128
| Field | Description | Default | Validation |
129129
| --- | --- | --- | --- |
130130
| `name` _string_ | Name of the guest (pipe \| should be escaped) | | MaxLength: 80 <br />Pattern: `0*[a-z0-9]*[a-z]*[0-9]` <br />Required: \{\} <br /> |
131131
| `tags` _string array_ | Tags of the entry. | | items:Pattern: `[a-z]*` <br /> |
132132
| `time` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#time-v1-meta)_ | Time of entry | | |
133133
| `comment` _string_ | Comment by guest. This can be a multi-line comment.<br />Like this one.<br />Now let's test a list:<br />* a<br />* b<br />Another isolated comment.<br />Looks good? | | Pattern: `0*[a-z0-9]*[a-z]*[0-9]*\|\s` <br /> |
134-
| `rating` _[Rating](#rating)_ | Rating provided by the guest | | Maximum: 5 <br />Minimum: 1 <br /> |
134+
| `rating` _[Rating](#github-com-elastic-crd-ref-docs-api-v1-rating)_ | Rating provided by the guest | | Maximum: 5 <br />Minimum: 1 <br /> |
135135
| `email` _string_ | Email is the email address of the guest (required field using +required marker) | | Required: \{\} <br /> |
136136
| `location` _string_ | Location is the location of the guest (required field using +k8s:required marker) | | Required: \{\} <br /> |
137137
| `phone` _string_ | Phone is the phone number of the guest (optional field using +optional marker) | | Optional: \{\} <br /> |
138138
| `company` _string_ | Company is the company of the guest (optional field using +k8s:optional marker) | | Optional: \{\} <br /> |
139139

140140

141-
#### GuestbookHeader
141+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-guestbookheader">GuestbookHeader</a>
142142

143143
_Underlying type:_ _string_
144144

@@ -147,11 +147,11 @@ GuestbookHeaders are strings to include at the top of a page.
147147

148148

149149
_Appears in:_
150-
- [GuestbookSpec](#guestbookspec)
150+
- [GuestbookSpec](#github-com-elastic-crd-ref-docs-api-v1-guestbookspec)
151151

152152

153153

154-
#### GuestbookList
154+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-guestbooklist">GuestbookList</a>
155155

156156

157157

@@ -166,10 +166,10 @@ GuestbookList contains a list of Guestbook.
166166
| `apiVersion` _string_ | `webapp.test.k8s.elastic.co/v1` | | |
167167
| `kind` _string_ | `GuestbookList` | | |
168168
| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
169-
| `items` _[Guestbook](#guestbook) array_ | | | |
169+
| `items` _[Guestbook](#github-com-elastic-crd-ref-docs-api-v1-guestbook) array_ | | | |
170170

171171

172-
#### GuestbookSpec
172+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-guestbookspec">GuestbookSpec</a>
173173

174174

175175

@@ -178,23 +178,23 @@ GuestbookSpec defines the desired state of Guestbook.
178178

179179

180180
_Appears in:_
181-
- [Guestbook](#guestbook)
181+
- [Guestbook](#github-com-elastic-crd-ref-docs-api-v1-guestbook)
182182

183183
| Field | Description | Default | Validation |
184184
| --- | --- | --- | --- |
185-
| `page` _[PositiveInt](#positiveint)_ | Page indicates the page number | 1 | Minimum: 1 <br /> |
186-
| `entries` _[GuestbookEntry](#guestbookentry) array_ | Entries contain guest book entries for the page | | |
185+
| `page` _[PositiveInt](#github-com-elastic-crd-ref-docs-api-v1-positiveint)_ | Page indicates the page number | 1 | Minimum: 1 <br /> |
186+
| `entries` _[GuestbookEntry](#github-com-elastic-crd-ref-docs-api-v1-guestbookentry) array_ | Entries contain guest book entries for the page | | |
187187
| `selector` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#labelselector-v1-meta)_ | Selector selects something | | |
188-
| `headers` _[GuestbookHeader](#guestbookheader) array_ | Headers contains a list of header items to include in the page | | MaxItems: 10 <br />UniqueItems: true <br /> |
188+
| `headers` _[GuestbookHeader](#github-com-elastic-crd-ref-docs-api-v1-guestbookheader) array_ | Headers contains a list of header items to include in the page | | MaxItems: 10 <br />UniqueItems: true <br /> |
189189
| `certificateRef` _[SecretObjectReference](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference)_ | CertificateRef is a reference to a secret containing a certificate | | |
190-
| `str` _[CommonString](#commonstring)_ | | | |
191-
| `enum` _[MyEnum](#myenum)_ | Enumeration is an example of an aliased enumeration type | | Enum: [MyFirstValue MySecondValue] <br /> |
190+
| `str` _[CommonString](#github-com-elastic-crd-ref-docs-api-common-commonstring)_ | | | |
191+
| `enum` _[MyEnum](#github-com-elastic-crd-ref-docs-api-v1-myenum)_ | Enumeration is an example of an aliased enumeration type | | Enum: [MyFirstValue MySecondValue] <br /> |
192192
| `digest` _string_ | Digest is the content-addressable identifier of the guestbook | | Pattern: `^sha256:[a-fA-F0-9]\{64\}$` <br /> |
193193

194194

195195

196196

197-
#### MyEnum
197+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-myenum">MyEnum</a>
198198

199199
_Underlying type:_ _string_
200200

@@ -204,15 +204,15 @@ _Validation:_
204204
- Enum: [MyFirstValue MySecondValue]
205205

206206
_Appears in:_
207-
- [GuestbookSpec](#guestbookspec)
207+
- [GuestbookSpec](#github-com-elastic-crd-ref-docs-api-v1-guestbookspec)
208208

209209
| Field | Description |
210210
| --- | --- |
211211
| `MyFirstValue` | MyFirstValue is an interesting value to use<br /> |
212212
| `MySecondValue` | MySecondValue is what you use when you can't use MyFirstValue<br /> |
213213

214214

215-
#### PositiveInt
215+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-positiveint">PositiveInt</a>
216216

217217
_Underlying type:_ _integer_
218218

@@ -222,11 +222,11 @@ _Validation:_
222222
- Minimum: 1
223223

224224
_Appears in:_
225-
- [GuestbookSpec](#guestbookspec)
225+
- [GuestbookSpec](#github-com-elastic-crd-ref-docs-api-v1-guestbookspec)
226226

227227

228228

229-
#### Rating
229+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-rating">Rating</a>
230230

231231
_Underlying type:_ _integer_
232232

@@ -237,13 +237,13 @@ _Validation:_
237237
- Minimum: 1
238238

239239
_Appears in:_
240-
- [GuestbookEntry](#guestbookentry)
240+
- [GuestbookEntry](#github-com-elastic-crd-ref-docs-api-v1-guestbookentry)
241241

242242

243243

244244

245245

246-
#### Underlying
246+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-underlying">Underlying</a>
247247

248248

249249

@@ -258,24 +258,24 @@ Underlying tests that Underlying1's underlying type is Underlying2 instead of st
258258
| `apiVersion` _string_ | `webapp.test.k8s.elastic.co/v1` | | |
259259
| `kind` _string_ | `Underlying` | | |
260260
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
261-
| `a` _[Underlying1](#underlying1)_ | | b | MaxLength: 10 <br /> |
261+
| `a` _[Underlying1](#github-com-elastic-crd-ref-docs-api-v1-underlying1)_ | | b | MaxLength: 10 <br /> |
262262

263263

264-
#### Underlying1
264+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-underlying1">Underlying1</a>
265265

266-
_Underlying type:_ _[Underlying2](#underlying2)_
266+
_Underlying type:_ _[Underlying2](#github-com-elastic-crd-ref-docs-api-v1-underlying2)_
267267

268268
Underlying1 has an underlying type with an underlying type
269269

270270
_Validation:_
271271
- MaxLength: 10
272272

273273
_Appears in:_
274-
- [Underlying](#underlying)
274+
- [Underlying](#github-com-elastic-crd-ref-docs-api-v1-underlying)
275275

276276

277277

278-
#### Underlying2
278+
#### <a id="github-com-elastic-crd-ref-docs-api-v1-underlying2">Underlying2</a>
279279

280280
_Underlying type:_ _string_
281281

@@ -285,7 +285,7 @@ _Validation:_
285285
- MaxLength: 10
286286

287287
_Appears in:_
288-
- [Underlying1](#underlying1)
288+
- [Underlying1](#github-com-elastic-crd-ref-docs-api-v1-underlying1)
289289

290290

291291

0 commit comments

Comments
 (0)