docs: update markdown template (#571)

Co-authored-by: Ariana W. <[email protected]>
solo-io · Nov 20, 2024 · dbc3d5e · dbc3d5e
1 parent 57e43a2
commit dbc3d5e
Show file tree

Hide file tree

Showing 6 changed files with 43 additions and 15 deletions.
diff --git a/changelog/v0.36.3/format-markdown-files.yaml b/changelog/v0.36.3/format-markdown-files.yaml
@@ -0,0 +1,6 @@
+changelog:
+- type: FIX
+  issueLink: https://github.com/solo-io/solo-projects/issues/6612
+  resolvesIssue: false
+  description: >-
+    Update the markdown templates to fit new formatting guidelines.
diff --git a/pkg/code-generator/docgen/generator.go b/pkg/code-generator/docgen/generator.go
@@ -147,22 +147,42 @@ func (d *DocsGen) FileHeader(filename string) string {
 		return ".. Code generated by solo-kit. DO NOT EDIT."
 	}
 	if d.DocsOptions.Output == options.Hugo {
-		name := filepath.Base(filename)
-		if strings.HasSuffix(name, d.protoSuffix()) {
-			name = name[:len(name)-len(d.protoSuffix())]
-		}
-		return fmt.Sprintf(`
+		return d.hugoFileHeader(filename)
+	}
+	return `<!-- Code generated by solo-kit. DO NOT EDIT. -->
+`
+}
+
+func (d *DocsGen) hugoFileHeader(filename string) string {
+	name := filepath.Base(filename)
+
+	// By default, the title of the page should match the file name
+	var title = name
+
+	// Any files with an .sk.* suffix is one that is generated by solo-kit
+	// The title shouldn't include this suffix, so we remove it
+	if strings.HasSuffix(name, d.protoSuffix()) {
+		title = strings.TrimSuffix(name, d.protoSuffix())
+	}
+
+	// For proto files:
+	//	- The title should not include the proto.sk.md suffix
+	//	- The title should be CamelCase
+	// This means that custom_resource.proto.sk.md will have a title of CustomResource
+	protoSuffix := ".proto"
+	if strings.HasSuffix(title, protoSuffix) {
+		title = strcase.ToCamel(strings.TrimSuffix(title, protoSuffix))
+	}
+
+	return fmt.Sprintf(`
 ---
 title: "%s"
 weight: 5
 ---
 
 <!-- Code generated by solo-kit. DO NOT EDIT. -->
 
-`, name)
-	}
-	return `<!-- Code generated by solo-kit. DO NOT EDIT. -->
-`
+`, title)
 }
 
 func (d *DocsGen) projectSuffix() string {

diff --git a/pkg/code-generator/docgen/templates/markdown/proto_file_template.go b/pkg/code-generator/docgen/templates/markdown/proto_file_template.go
@@ -25,7 +25,7 @@ func ProtoFileTemplate(project *model.Project, docsOptions *options.DocsOptions)
 {{ end }}
 
 {{- if gt (len .Messages) 0 }} 
-#### Types:
+**Types:**
 
 {{ $linkMessage :=  "- [{{ printfptr \"%v\" .Name }}](#{{ toAnchorLink \"%v\" .Name }}) {{- if (resourceForMessage .) }} **Top-Level Resource**{{ end }}" }}
 {{ $linkEnum :=  "- [{{ printfptr \"%v\" .Name }}](#{{ toAnchorLink \"%v\" .Name }})" }}
@@ -35,7 +35,7 @@ func ProtoFileTemplate(project *model.Project, docsOptions *options.DocsOptions)
 
 {{- if gt (len .Enums) 0 }} 
 
-##### Enums:
+**Enums:**
 
 {{ range .Enums}}
 	- [{{ printfptr "%v" .Name }}](#{{ toAnchorLink "%v" .Name }})
@@ -44,7 +44,7 @@ func ProtoFileTemplate(project *model.Project, docsOptions *options.DocsOptions)
 
 {{ end}}
 
-##### Source File: {{ githubLinkForFile "main" .Name }}
+**Source File: {{ githubLinkForFile "main" .Name }}**
 
 {{ $msgLongInfo :=  ` + "`" + `
 {{ $Message := . -}}

diff --git a/pkg/code-generator/schemagen/crd.go b/pkg/code-generator/schemagen/crd.go
@@ -22,6 +22,8 @@ const (
 	v1 = "apiextensions.k8s.io/v1"
 )
 
+const crdFileHeader = `CRD validation schema generated by solo-kit. DO NOT EDIT.`
+
 var (
 	ApiVersionMismatch = func(expected, actual string) error {
 		return eris.Errorf("Expected ApiVersion [%s] but found [%s]", expected, actual)
@@ -37,7 +39,7 @@ func NewCrdWriter(crdDirectory string) *CrdWriter {
 		fileWriter: &writer.DefaultFileWriter{
 			Root: crdDirectory,
 			HeaderFromFilename: func(s string) string {
-				return fmt.Sprintf("# %s\n\n", writer.DefaultFileHeader)
+				return fmt.Sprintf("# %s\n\n", crdFileHeader)
 			},
 		},
 	}

diff --git a/test/mocks/crds/testing.solo.io_v1_MockResource.yaml b/test/mocks/crds/testing.solo.io_v1_MockResource.yaml
@@ -1,4 +1,4 @@
-# Code generated by solo-kit. DO NOT EDIT.
+# CRD validation schema generated by solo-kit. DO NOT EDIT.
 
 apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition

diff --git a/test/mocks/crds/testing.solo.io_v1_SimpleMockResource.yaml b/test/mocks/crds/testing.solo.io_v1_SimpleMockResource.yaml
@@ -1,4 +1,4 @@
-# Code generated by solo-kit. DO NOT EDIT.
+# CRD validation schema generated by solo-kit. DO NOT EDIT.
 
 apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition