feat: add resource doc template and mise task (#2540)

* feat: add resource doc template with gomplate

Add template and tooling for creating new resource reference docs:
- templates/resource.md with Go template syntax
- gomplate as mise dependency for template rendering
- mise new:resource task for doc generation

Usage: mise new:resource MeshService
Signed-off-by: Marcin Skalski <skalskimarcin33@gmail.com>

* update fronmatter

Signed-off-by: Marcin Skalski <skalskimarcin33@gmail.com>

---------

Signed-off-by: Marcin Skalski <skalskimarcin33@gmail.com>

Author: Automaat

.github/workflows/ci.yml

@@ -153,6 +153,7 @@ jobs:
               .filter(d => d.status != "removed")
               .filter(d => !d.filename.includes("/generated/"))
               .filter(d => !d.filename.includes("/raw/"))
+              .filter(d => !d.filename.startsWith("templates/"))
               .map(d => d.filename);
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # v2.1.1

CONTRIBUTING.md

@@ -74,6 +74,16 @@ mise vale:branch        # Run Vale linter only
 mise vale:version-urls  # Run version URL checker only
 ```
 
+#### Creating new resource docs
+
+To create a new resource reference doc from template:
+
+```sh
+mise new:resource MeshService
+```
+
+This creates `app/_src/resources/meshservice.md` from the template. Update the nav file after creation.
+
 #### Page metadata
 
 All documentation pages should include frontmatter metadata for SEO and search:

mise.toml

@@ -8,6 +8,7 @@ yarn = "1.22.22"
 vale = "3.13.0"
 shellcheck = "0.10.0"
 "go:github.com/raviqqe/muffet/v2" = "v2.11.0"
+"go:github.com/hairyhenderson/gomplate/v4/cmd/gomplate" = "v4.3.0"
 shellspec = "0.28.1"
 
 [tasks.install]
@@ -106,6 +107,7 @@ git diff --name-only --diff-filter=d origin/master...HEAD | \
   grep -E '\\.(md|markdown)$' | \
   grep -v '/generated/' | \
   grep -v '/raw/' | \
+  grep -v '^templates/' | \
   xargs -r vale
 """
 
@@ -128,3 +130,20 @@ run = "shellcheck tools/*.sh"
 [tasks.check]
 description = "Run necessary checks"
 depends = ["vale:branch", "vale:version-urls", "frontmatter:validate"]
+
+[tasks."new:resource"]
+description = "Create new resource reference doc"
+run = '''
+RESOURCE_NAME={{arg(name="resource")}}
+LOWERCASE=$(echo "$RESOURCE_NAME" | tr '[:upper:]' '[:lower:]')
+OUTPUT="app/_src/resources/${LOWERCASE}.md"
+if [ -f "$OUTPUT" ]; then
+  echo "Error: $OUTPUT already exists" >&2
+  exit 1
+fi
+mkdir -p app/_src/resources
+export RESOURCE_NAME
+gomplate -f templates/resource.md -o "$OUTPUT"
+echo "Created $OUTPUT"
+echo "TODO: Update nav in latest app/_data/docs_nav_kuma_2.x.x.yml"
+'''

templates/resource.md

@@ -0,0 +1,58 @@
+---
+title: {{ .Env.RESOURCE_NAME }}
+description: TODO: Add description
+# Use exactly 3 keywords for optimal Algolia search performance
+keywords:
+  - {{ .Env.RESOURCE_NAME }}
+  - resource
+  - reference
+content_type: reference
+category: resource
+---
+
+TODO: Add introduction
+
+## Spec fields
+
+<!-- Document each spec field with:
+### fieldName
+
+Description of field purpose and behavior.
+
+**Type:** `type` | **Required:** Yes/No | **Default:** `value`
+
+#### nestedField (if applicable)
+-->
+
+## Examples
+
+### Basic {{ .Env.RESOURCE_NAME }}
+
+{% tabs %}
+{% tab Kubernetes %}
+
+```yaml
+apiVersion: kuma.io/v1alpha1
+kind: {{ .Env.RESOURCE_NAME }}
+metadata:
+  name: example
+```
+
+{% endtab %}
+{% tab Universal %}
+
+```yaml
+type: {{ .Env.RESOURCE_NAME }}
+name: example
+```
+
+{% endtab %}
+{% endtabs %}
+
+## See also
+
+- [Related doc](/docs/{{ "{{" }} page.release {{ "}}" }}/path)
+
+## All options
+
+{% json_schema {{ .Env.RESOURCE_NAME }} type=proto %}