feat: add resource doc template and mise task

Add template and tooling for creating new resource reference docs:
- templates/resource.md with standard structure
- tools/new-resource-doc.sh generator script
- mise new:resource task
- shellspec tests

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

@@ -106,6 +106,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 +129,7 @@ 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 (usage: mise new:resource ResourceName)"
+run = "tools/new-resource-doc.sh \"$@\""

templates/resource.md

@@ -0,0 +1,57 @@
+---
+title: RESOURCE_TITLE
+description: RESOURCE_DESCRIPTION
+# Use exactly 3 keywords for optimal Algolia search performance
+keywords:
+  - KEYWORD1
+  - KEYWORD2
+  - KEYWORD3
+content_type: reference
+---
+
+RESOURCE_INTRO
+
+## 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 RESOURCE_NAME
+
+{% tabs %}
+{% tab Kubernetes %}
+
+```yaml
+apiVersion: kuma.io/v1alpha1
+kind: RESOURCE_NAME
+metadata:
+  name: example
+```
+
+{% endtab %}
+{% tab Universal %}
+
+```yaml
+type: RESOURCE_NAME
+name: example
+```
+
+{% endtab %}
+{% endtabs %}
+
+## See also
+
+- [Related doc](/docs/{{ page.release }}/path)
+
+## All options
+
+{% json_schema RESOURCE_NAME type=proto %}

tools/new-resource-doc.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Creates new resource reference doc from template
+# Usage: tools/new-resource-doc.sh <ResourceName>
+
+RESOURCE_NAME="${1:-}"
+if [ -z "$RESOURCE_NAME" ]; then
+  echo "Usage: $0 <ResourceName>" >&2
+  exit 1
+fi
+
+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
+sed "s/RESOURCE_NAME/$RESOURCE_NAME/g; \
+     s/RESOURCE_TITLE/$RESOURCE_NAME/g; \
+     s/RESOURCE_DESCRIPTION/TODO: Add description/g; \
+     s/RESOURCE_INTRO/TODO: Add introduction/g; \
+     s/KEYWORD1/$RESOURCE_NAME/g; \
+     s/KEYWORD2/resource/g; \
+     s/KEYWORD3/reference/g" \
+  templates/resource.md > "$OUTPUT"
+
+echo "Created $OUTPUT"
+echo "TODO: Update nav in latest app/_data/docs_nav_kuma_2.x.x.yml"

tools/spec/new_resource_doc_spec.sh

@@ -0,0 +1,75 @@
+Describe 'new-resource-doc.sh'
+  ORIG_DIR="$PWD"
+  SCRIPT_UNDER_TEST="$ORIG_DIR/tools/new-resource-doc.sh"
+
+  setup_workspace() {
+    TEST_DIR=$(mktemp -d)
+    cd "$TEST_DIR"
+    mkdir -p templates
+    cat > templates/resource.md << 'TEMPLATE'
+---
+title: RESOURCE_TITLE
+description: RESOURCE_DESCRIPTION
+keywords:
+  - KEYWORD1
+content_type: reference
+---
+
+## Examples
+
+### Basic RESOURCE_NAME
+
+{% json_schema RESOURCE_NAME type=proto %}
+TEMPLATE
+  }
+
+  cleanup_workspace() {
+    cd "$ORIG_DIR"
+    rm -rf "$TEST_DIR"
+  }
+
+  BeforeEach 'setup_workspace'
+  AfterEach 'cleanup_workspace'
+
+  Describe 'argument validation'
+    It 'fails when no resource name provided'
+      When run "$SCRIPT_UNDER_TEST"
+      The status should be failure
+      The stderr should include "Usage:"
+    End
+  End
+
+  Describe 'file creation'
+    It 'creates resource doc with lowercase filename'
+      When run "$SCRIPT_UNDER_TEST" MeshService
+      The status should be success
+      The output should include "Created app/_src/resources/meshservice.md"
+      The file "app/_src/resources/meshservice.md" should be exist
+    End
+
+    It 'replaces placeholders correctly'
+      "$SCRIPT_UNDER_TEST" MeshGateway
+      When run cat app/_src/resources/meshgateway.md
+      The output should include "title: MeshGateway"
+      The output should include "description: TODO: Add description"
+      The output should include "- MeshGateway"
+      The output should include "### Basic MeshGateway"
+      The output should include "{% json_schema MeshGateway type=proto %}"
+    End
+
+    It 'fails when file already exists'
+      mkdir -p app/_src/resources
+      echo "existing" > app/_src/resources/mesh.md
+      When run "$SCRIPT_UNDER_TEST" Mesh
+      The status should be failure
+      The stderr should include "already exists"
+    End
+  End
+
+  Describe 'output messages'
+    It 'shows TODO reminder for nav update'
+      When run "$SCRIPT_UNDER_TEST" TestResource
+      The output should include "TODO: Update nav"
+    End
+  End
+End