Emit API reference as structured Hugo shortcodes instead of HTML tables

[Caesarsage]

Motivation

The current gen-apidocs markdown backend emits API reference pages as HTML tables. This works, but couples presentation to content.

A shortcode-based approach would separate structured data (field metadata) from presentation (template rendering):

{{< api-reference-subfield >}}
---
apiKind: Deployment
topLevelFieldName: spec
childFieldName: selector
fieldType: LabelSelector
fieldRequired: true
---
Field description here.
{{< /api-reference-subfield >}}

Benefits:

• Structured data accessible to Hugo templates (enables different rendering modes from the same source)
• Presentation changes via one template, not N pages
• Responsive layouts per device via Hugo template logic

Prerequisites

• New shortcodes defined in k/website: api-reference-toplevel, api-reference-description, api-reference-subfield,
• gen-apidocs markdown backend updated to emit these instead of
• Cross-repo coordination (design RFC → shortcodes land in k/website → gen-apidocs output updated)

Related

• Follow-up to Merge gen-resourcesdocs into gen-apidocs #434 completion (markdown backend consolidation): This will give direction
• Suggested by @lmktfy extend gen-apidocs with a markdown backend #435 (comment)

[lmktfy]

I don't agree with the machine readable part; we have OpenAPI for that.

But, emitting a set of shortcodes in Markdown from the generator allows for flexible rendering within Hugo. A single set of Markdown files could render out as any of all of:

• single page API reference
• printable API reference
• embedded quick reference within related docs pages
• API reference across multiple pages with navigation

etc

[lmktfy]

We can actually emit this set of Markdown files as soon as there are skeleton, placeholder shortcodes in place (empty files).

We don't need to block the reference-docs changes on putting actual HTML and Go templates into those shortcode layout files.

[Caesarsage]

Thanks, fair point that OpenAPI is the source for external tooling. I'll reframe that bullet point.

[Caesarsage]

Truly empty shortcodes render as empty output, so we'd need pass-through templates upfront which still means agreeing on shortcode shape first.

Happy to drive that design here once the next PR land. That PR settles the nested field model, giving us a stable structure to design shortcodes against.

[tengqm]

I'm okay with using shortcodes in the website when they help automate/simplify things somehow. I'm not in favor of emitting shortcodes in the output from reference generator.
Hugo is just one of the themes for technical docs. There are many of them.
Let's keep the output as markdown/HTML, please.

[Caesarsage]

That makes sense. I agree the default output should stay portable Markdown/HTML.

we can still explore the Hugo rendering path, would be an explicit opt-in output mode, for example --output-mode=hugo-shortcodes, rather than replacing the default generator output.