coder/scripts/docgenenv/frontmatter.go

package docgenenv

import "strings"

// generatedMarker is the YAML comment placed as the first line inside every
// generated reference page's front matter. It follows the canonical
// "Code generated ... DO NOT EDIT." convention so the signal is recognizable at
// the top of the file. Because it lives inside the front matter fence, every
// coder.com surface (rendered HTML, the .md proxy twin, and the llms corpus)
// strips it with the rest of the block, so it never reaches readers.
const generatedMarker = "# Code generated by make gen. DO NOT EDIT."

// GeneratedContentBanner is the HTML comment placed in the Markdown body of
// every generated reference page, directly below the front matter. The in-fence
// generatedMarker flags the page metadata as generated; this body banner flags
// the whole page as generated, so an editor who reads past the front matter is
// still warned. Both documentation generators reference this one constant so
// the wording cannot drift between them.
const GeneratedContentBanner = "<!-- DO NOT EDIT | GENERATED CONTENT -->"

// FrontMatter renders r's metadata (title plus any description, icon_path, and
// state) as a YAML front matter block. The block opens with generatedMarker,
// carries the fences, and ends with the blank line that separates it from the
// Markdown body. Optional fields are omitted when empty.
//
// Both documentation generators emit their front matter through this single
// function so a new per-page metadata field is wired in one place instead of
// drifting between the CLI template and the API generator. Structural manifest
// fields (path, children) are intentionally not mirrored here.
func FrontMatter(r Route) string {
	// strings.Builder and bytes.Buffer expose only error-returning Write
	// methods, which the revive unhandled-error linter flags, so assemble the
	// block as a []string and join it.
	lines := []string{
		"---",
		generatedMarker,
		"title: " + YAMLScalar(r.Title),
	}
	if r.Description != "" {
		lines = append(lines, "description: "+YAMLScalar(r.Description))
	}
	if r.IconPath != "" {
		lines = append(lines, "icon_path: "+YAMLScalar(r.IconPath))
	}
	if len(r.State) > 0 {
		lines = append(lines, "state:")
		for _, s := range r.State {
			lines = append(lines, "  - "+YAMLScalar(s))
		}
	}
	// The trailing empty strings produce the closing fence followed by the
	// blank line that must separate front matter from the body.
	lines = append(lines, "---", "", "")
	return strings.Join(lines, "\n")
}

// GeneratedHeader returns the full generated-page preamble: the front matter
// block (from FrontMatter) followed by GeneratedContentBanner and the blank
// line before the Markdown body. The API generator prepends this to every page
// so CLI and API reference pages share the same two markers; the CLI template
// composes the equivalent preamble inline from the frontMatter and
// generatedContentBanner template helpers.
func GeneratedHeader(r Route) string {
	return FrontMatter(r) + GeneratedContentBanner + "\n\n"
}