Skip to content

Commit b14fcd2

Browse files
jamesadevineCopilotCopilot
authored
docs: starlight site (#536)
* feat(compile): add target: job and target: stage for ADO template output Add two new compile targets that produce reusable ADO YAML templates for embedding agentic stages into existing pipelines: - target: job — generates a job-level template (jobs: at root) that can be included in a flat pipeline or inside a user-defined stage - target: stage — generates a stage-level template (stages: wrapping jobs) for direct inclusion in multi-stage pipelines Key design decisions: - Pool is baked in from front matter (not a template parameter) - dependsOn and condition are set natively at the ADO call site - Job names are prefixed with PascalCase agent name for uniqueness (e.g., DailyReview_Agent, DailyReview_Detection, DailyReview_Execution) - Triggers (on:) are ignored with a warning in template targets - Template parameters only include clearMemory and user-defined params New files: - src/compile/job.rs — JobCompiler implementing the Compiler trait - src/compile/stage.rs — StageCompiler implementing the Compiler trait - src/data/job-base.yml — job-level template derived from base.yml - src/data/stage-base.yml — stage-level template wrapping jobs in stage Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(compile): address PR review feedback for job/stage targets - Fix path corruption: use Path::with_extension instead of string replace to derive .lock.yml paths in header comments (avoids corrupting directory names containing '.md') - Fix repos header docs: only check front_matter.repositories (populated by resolve_repos() before compile) instead of also checking front_matter.repos (raw input, may be empty) - Fix Unicode in stage prefix: use is_ascii_alphanumeric() to split on non-ASCII characters, ensuring ADO-valid identifiers (ADO requires [A-Za-z0-9_] for job/stage names) - Add test for Unicode stripping in generate_stage_prefix Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(compile): implement review suggestions for job/stage template targets Agent-Logs-Url: https://github.com/githubnext/ado-aw/sessions/fa2ca612-1703-4107-87c3-2b2ec35429b8 Co-authored-by: jamesadevine <4742697+jamesadevine@users.noreply.github.com> * fix(compile): use 'template' label for job/stage targets and fix header paths - CLI now prints 'Generated job template:' and 'Generated stage template:' instead of 'Generated job pipeline:' / 'Generated stage pipeline:' since these targets produce reusable ADO templates, not standalone pipelines. - Header comments in generated job/stage templates now reference the actual output path instead of deriving a path from the input file, fixing incorrect inclusion examples (e.g. showing ./agents/x.lock.yml when the output was at ./x.lock.yml). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: scaffold Astro Starlight documentation site - Astro 6 + Starlight 0.38 with purple accent theme (Mona Sans font) - 26 content pages: Introduction, Setup, Guides, Reference, Troubleshooting - Agent-friendly endpoints: robots.txt, .well-known/ai.txt, /ai/*.json - starlight-llms-txt plugin for llms.txt/llms-full.txt/llms-small.txt - starlight-links-validator for build-time link checking - GitHub Actions workflow for GitHub Pages deployment - Content adapted from existing docs/ reference pages Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: update quick start with binary install, configure step, and Rust version - Primary install path is now downloading pre-built binaries from GH releases - Added platform tabs (Linux x64, macOS arm64, Windows x64) with download scripts - Added checksum verification instructions - Added ado-aw configure step (push → configure → run order) - Documented GitHub PAT temporary limitation (no App token support yet) - Local development page now specifies Rust 1.94.0+ requirement Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: replace Unicode chars with ASCII equivalents Replace em dashes, en dashes, smart quotes, ellipses, and arrows with their ASCII counterparts across all MDX content to avoid rendering issues. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: clear Astro cache on npm run dev Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: fix CustomHead to extend default Starlight Head The custom Head component was replacing the default entirely, dropping meta charset=utf-8 and other essential tags. Now extends the default Head component and appends custom content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: fix configure command description -- Azure CLI first, PAT fallback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: add GitHub PAT permission requirements Add dedicated GitHub PAT permissions section to quick start with required fine-grained PAT settings (Copilot Requests: Read, personal account owner). Update CLI configure command docs with Azure CLI fallback behavior and link to permission requirements. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: integrate astro-mermaid for diagram rendering Add astro-mermaid integration with autoTheme support (light/dark). Replace text-art pipeline flow diagram in How It Works with a proper Mermaid flowchart. Mermaid renders client-side with no external dependencies. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: redesign landing page with compelling messaging Rewrite the splash page with outcome-focused copy: security patch PRs, pipeline failure analysis, documentation consistency, work item triage. Add Mermaid security architecture diagram, tabbed agent-file vs compiled pipeline example, CardGrid sections, and clear CTAs to both quick start paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: refine hero with prominent title and inline example Title: Azure DevOps Agentic Workflows, subtitle: Continuous AI for Azure DevOps. Lead immediately with a real agent markdown example (Dependency Guardian) before the outcome copy. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: light mode polish, gh-aw crossover section, search styling Fix card rendering in light mode with explicit backgrounds, borders, and icon colors. Use theme-neutral Mermaid diagram colors. Style search box for splash pages. Add "Same salad, different dressing" section with gh-aw comparison table and restored footer attribution. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
1 parent f29f1d5 commit b14fcd2

58 files changed

Lines changed: 15435 additions & 12 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ Every compiled pipeline runs as three sequential jobs:
5252
│ │ ├── common.rs # Shared helpers across targets
5353
│ │ ├── standalone.rs # Standalone pipeline compiler
5454
│ │ ├── onees.rs # 1ES Pipeline Template compiler
55+
│ │ ├── job.rs # Job-level ADO template compiler (target: job)
56+
│ │ ├── stage.rs # Stage-level ADO template compiler (target: stage)
5557
│ │ ├── gitattributes.rs # .gitattributes management for compiled pipelines
5658
│ │ ├── filter_ir.rs # Filter expression IR: Fact/Predicate types, lowering, validation, codegen
5759
│ │ ├── pr_filters.rs # PR trigger filter generation (native ADO + gate steps)
@@ -122,6 +124,8 @@ Every compiled pipeline runs as three sequential jobs:
122124
│ ├── data/
123125
│ │ ├── base.yml # Base pipeline template for standalone
124126
│ │ ├── 1es-base.yml # Base pipeline template for 1ES target
127+
│ │ ├── job-base.yml # Job-level ADO template for target: job
128+
│ │ ├── stage-base.yml # Stage-level ADO template for target: stage
125129
│ │ ├── ecosystem_domains.json # Network allowlists per ecosystem
126130
│ │ ├── init-agent.md # Dispatcher agent template for `init` command
127131
│ │ └── threat-analysis.md # Threat detection analysis prompt template

‎docs-site/.github/workflows/deploy-docs.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Deploy Docs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths: ['docs-site/**']
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: true
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- uses: actions/setup-node@v4
25+
with:
26+
node-version: 22
27+
cache: npm
28+
cache-dependency-path: docs-site/package-lock.json
29+
30+
- name: Install dependencies
31+
working-directory: docs-site
32+
run: npm ci
33+
34+
- name: Build site
35+
working-directory: docs-site
36+
run: npm run build
37+
38+
- uses: actions/upload-pages-artifact@v3
39+
with:
40+
path: docs-site/dist
41+
42+
deploy:
43+
needs: build
44+
runs-on: ubuntu-latest
45+
environment:
46+
name: github-pages
47+
url: ${{ steps.deployment.outputs.page_url }}
48+
steps:
49+
- id: deployment
50+
uses: actions/deploy-pages@v4

‎docs-site/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules/
2+
dist/
3+
.astro/

‎docs-site/astro.config.mjs‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
import { defineConfig } from 'astro/config';
2+
import starlight from '@astrojs/starlight';
3+
import sitemap from '@astrojs/sitemap';
4+
import starlightLlmsTxt from 'starlight-llms-txt';
5+
import starlightLinksValidator from 'starlight-links-validator';
6+
import mermaid from 'astro-mermaid';
7+
8+
export default defineConfig({
9+
site: 'https://githubnext.github.io',
10+
base: '/ado-aw/',
11+
trailingSlash: 'always',
12+
integrations: [
13+
mermaid({ autoTheme: true }),
14+
starlight({
15+
title: 'ado-aw',
16+
description: 'Compile natural-language markdown into Azure DevOps agentic pipelines',
17+
plugins: [
18+
starlightLlmsTxt(),
19+
starlightLinksValidator(),
20+
],
21+
customCss: ['./src/styles/custom.css'],
22+
components: {
23+
Head: './src/components/CustomHead.astro',
24+
},
25+
tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 4 },
26+
social: [
27+
{ icon: 'github', label: 'GitHub', href: 'https://github.com/githubnext/ado-aw' },
28+
],
29+
sidebar: [
30+
{
31+
label: 'Introduction',
32+
autogenerate: { directory: 'introduction' },
33+
},
34+
{
35+
label: 'Setup',
36+
items: [
37+
{ label: 'Quick Start', slug: 'setup/quick-start' },
38+
{ label: 'CLI Commands', slug: 'setup/cli' },
39+
{ label: 'Local Development', slug: 'setup/local-development' },
40+
],
41+
},
42+
{
43+
label: 'Guides',
44+
items: [
45+
{ label: 'Creating Agents', slug: 'guides/creating-agents' },
46+
{ label: 'Network Configuration', slug: 'guides/network-config' },
47+
{ label: 'Schedule Syntax', slug: 'guides/schedule-syntax' },
48+
{ label: 'Using MCP', slug: 'guides/using-mcp' },
49+
{ label: 'Extending the Compiler', slug: 'guides/extending' },
50+
],
51+
},
52+
{
53+
label: 'Reference',
54+
items: [
55+
{ label: 'Front Matter', slug: 'reference/front-matter' },
56+
{ label: 'Engine', slug: 'reference/engine' },
57+
{ label: 'Parameters', slug: 'reference/parameters' },
58+
{ label: 'Tools', slug: 'reference/tools' },
59+
{ label: 'Runtimes', slug: 'reference/runtimes' },
60+
{ label: 'Safe Outputs', slug: 'reference/safe-outputs' },
61+
{ label: 'Targets', slug: 'reference/targets' },
62+
{ label: 'Network', slug: 'reference/network' },
63+
{ label: 'MCP', slug: 'reference/mcp' },
64+
{ label: 'MCP Gateway', slug: 'reference/mcpg' },
65+
{ label: 'Template Markers', slug: 'reference/template-markers' },
66+
{ label: 'Filter IR', slug: 'reference/filter-ir' },
67+
{ label: 'Codemods', slug: 'reference/codemods' },
68+
],
69+
},
70+
{
71+
label: 'Troubleshooting',
72+
autogenerate: { directory: 'troubleshooting' },
73+
},
74+
],
75+
}),
76+
sitemap(),
77+
],
78+
});

0 commit comments

Comments
 (0)