Add custom 'aw' language definition for agentic workflow syntax highlighting

docs/astro.config.mjs

@@ -4,7 +4,44 @@ import starlight from '@astrojs/starlight';
 import starlightLlmsTxt from 'starlight-llms-txt';
 import starlightLinksValidator from 'starlight-links-validator';
 import starlightGitHubAlerts from 'starlight-github-alerts';
-import starlightChangelogs, { makeChangelogsSidebarLinks } from 'starlight-changelogs';
+// import starlightChangelogs, { makeChangelogsSidebarLinks } from 'starlight-changelogs';
+
+// Define custom language for agentic workflows (frontmatter + markdown)
+const awLanguageDefinition = {
+	id: "aw",
+	scopeName: "source.aw",
+	aliases: ["agentic-workflow", "frontmatter-markdown"],
+	grammar: {
+		name: "Agentic Workflow",
+		scopeName: "source.aw",
+		fileTypes: ["aw"],
+		patterns: [
+			{
+				// YAML frontmatter block
+				name: "meta.embedded.block.frontmatter",
+				begin: "^(---)\\s*$",
+				beginCaptures: {
+					"1": { name: "punctuation.definition.tag.begin.yaml" }
+				},
+				end: "^(---)\\s*$",
+				endCaptures: {
+					"1": { name: "punctuation.definition.tag.end.yaml" }
+				},
+				patterns: [
+					{ include: "source.yaml" }
+				]
+			},
+			{
+				// Markdown content after frontmatter
+				begin: "(?<=^---\\s*$\\s*)",
+				end: "\\z",
+				patterns: [
+					{ include: "text.html.markdown" }
+				]
+			}
+		]
+	}
+};
 
 // https://astro.build/config
 export default defineConfig({
@@ -17,8 +54,17 @@ export default defineConfig({
 				{ icon: 'github', label: 'GitHub', href: 'https://github.com/githubnext/gh-aw' },
 				{ icon: 'rocket', label: 'Instructions', href: 'https://raw.githubusercontent.com/githubnext/gh-aw/main/pkg/cli/templates/instructions.md' }
 			],
+			expressiveCode: {
+				shiki: {
+					langs: [
+						"markdown",
+						"yaml",
+						awLanguageDefinition
+					],
+				},
+			},
 			plugins: [
-				starlightChangelogs(),
+				// starlightChangelogs(),
 				starlightGitHubAlerts(),
 				starlightLinksValidator({
 					errorOnRelativeLinks: true,
@@ -61,9 +107,9 @@ export default defineConfig({
 					label: 'Application Areas',
 					autogenerate: { directory: 'samples' },
 				},
-				...makeChangelogsSidebarLinks([
-					{ type: 'all', base: 'changelog', label: 'Changelog' }
-				]),
+				// ...makeChangelogsSidebarLinks([
+				// 	{ type: 'all', base: 'changelog', label: 'Changelog' }
+				// ]),
 			],
 		}),
 	],

docs/src/content.config.ts

@@ -1,21 +1,21 @@
 import { defineCollection } from 'astro:content';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
-import { changelogsLoader } from 'starlight-changelogs/loader';
+// import { changelogsLoader } from 'starlight-changelogs/loader';
 
 export const collections = {
 	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
-	changelogs: defineCollection({
-		loader: changelogsLoader([
-			{
-				provider: 'github',       // use GitHub releases as changelog source
-				base: 'changelog',        // base path for changelog pages
-				owner: 'githubnext',      // GitHub org/user
-				repo: 'gh-aw',            // GitHub repo
-				// Use GitHub token if available in environment, otherwise rely on public API
-				...(process.env.GITHUB_TOKEN && { token: process.env.GITHUB_TOKEN }),
-				// No process filter: include all releases
-			},
-		]),
-	}),
+	// changelogs: defineCollection({
+	// 	loader: changelogsLoader([
+	// 		{
+	// 			provider: 'github',       // use GitHub releases as changelog source
+	// 			base: 'changelog',        // base path for changelog pages
+	// 			owner: 'githubnext',      // GitHub org/user
+	// 			repo: 'gh-aw',            // GitHub repo
+	// 			// Use GitHub token if available in environment, otherwise rely on public API
+	// 			...(process.env.GITHUB_TOKEN && { token: process.env.GITHUB_TOKEN }),
+	// 			// No process filter: include all releases
+	// 		},
+	// 	]),
+	// }),
 };

docs/src/content/docs/guides/chatops.md

@@ -11,7 +11,7 @@ GitHub Agentic Workflows makes ChatOps natural and secure through command trigge
 
 Command triggers make any GitHub repository responsive to automation commands. When you configure a command trigger, your workflow automatically listens for specific slash commands in issues, pull requests, and comments.
 
-```yaml
+```aw
 ---
 on:
   command:
@@ -47,7 +47,7 @@ You can customize access using the `roles:` configuration, but using `roles: all
 
 ChatOps workflows have access to sanitized context from the triggering event through `needs.activation.outputs.text`. This provides safer access to issue content, pull request details, or comment text with reduced security risks.
 
-```yaml
+```markdown
 # In your workflow content, reference the sanitized text:
 Analyze this content: "${{ needs.activation.outputs.text }}"
 ```

docs/src/content/docs/reference/safe-outputs.md

@@ -94,7 +94,20 @@ The agentic part of your workflow should describe the comment(s) it wants posted
 
 **Example natural language to generate the output:**
 
-```markdown
+```aw
+---
+on:
+  issues:
+    types: [opened, edited]
+permissions:
+  contents: read
+  actions: read
+engine: claude
+safe-outputs:
+  add-comment:
+    max: 3
+---
+
 # Issue/PR Analysis Agent
 
 Analyze the issue or pull request and provide feedback.
@@ -161,7 +174,22 @@ The agentic part of your workflow should analyze the issue and determine what up
 
 **Example natural language to generate the output:**
 
-```markdown
+```aw
+---
+on:
+  issues:
+    types: [opened, edited]
+permissions:
+  contents: read
+  actions: read
+engine: claude
+safe-outputs:
+  update-issue:
+    status: true
+    title: true
+    body: true
+---
+
 # Issue Update Agent
 
 Analyze the issue and update its status, title, or body as needed.
@@ -253,7 +281,22 @@ The agentic part of your workflow should instruct to:
 
 **Example natural language to generate the output:**
 
-```markdown
+```aw
+---
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+  actions: read
+engine: claude
+safe-outputs:
+  create-pull-request:
+    title-prefix: "[ai] "
+    labels: [automation, code-improvement]
+    draft: true
+---
+
 # Code Improvement Agent
 
 Analyze the latest commit and suggest improvements.
@@ -284,7 +327,21 @@ The agentic part of your workflow should describe the review comment(s) it wants
 
 **Example natural language to generate the output:**
 
-```markdown
+```aw
+---
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+permissions:
+  contents: read
+  actions: read
+engine: claude
+safe-outputs:
+  create-pull-request-review-comment:
+    max: 3
+    side: "RIGHT"
+---
+
 # Code Review Agent
 
 Analyze the pull request changes and provide line-specific feedback.
@@ -392,7 +449,21 @@ The agentic part of your workflow should describe the changes to be pushed and o
 
 **Example natural language to generate the output:**
 
-```markdown
+```aw
+---
+on:
+  pull_request:
+    types: [opened, synchronize]
+permissions:
+  contents: read
+  actions: read
+engine: claude
+safe-outputs:
+  push-to-pull-request-branch:
+    target: "triggering"
+    if-no-changes: "warn"
+---
+
 # Code Update Agent
 
 Analyze the pull request and make necessary code improvements.
@@ -475,7 +546,20 @@ The agentic part of your workflow can report missing tools or functionality that
 
 **Example natural language to generate the output:**
 
-```markdown
+```aw
+---
+on:
+  issues:
+    types: [opened]
+permissions:
+  contents: read
+  actions: read
+engine: claude
+safe-outputs:
+  missing-tool:
+    max: 10
+---
+
 # Development Task Agent
 
 Analyze the repository and implement the requested feature. If you encounter missing tools, capabilities, or permissions that prevent completion, report them so the user can address these limitations.

docs/src/content/docs/reference/workflow-structure.md

@@ -16,7 +16,7 @@ The markdown content is where you write natural language instructions for the AI
 
 Create a markdown file in `.github/workflows/` with the following structure:
 
-```markdown
+```aw
 ---
 on:
   issues: