docs(website): add Docusaurus documentation site#29
Open
sendtoshailesh wants to merge 2 commits intomainfrom
Open
docs(website): add Docusaurus documentation site#29sendtoshailesh wants to merge 2 commits intomainfrom
sendtoshailesh wants to merge 2 commits intomainfrom
Conversation
Add full Docusaurus 3.x website infrastructure with: - Landing page with hero, metrics, personas, capabilities - Auto-generated docs from agents, skills, workflows - GitHub Actions workflows for Pages deployment - Doc staleness check workflow for PRs - README docs link to azure.github.io/git-ape 🤖 - Generated by Copilot
Remove AWS skill docs, CloudFormation examples, and AWS references from landing page and deployment state docs. AWS support is not yet ready for public announcement. - Delete 21 AWS skill doc files - Update landing page metrics and descriptions - Remove AWS sections from deployment/state.md - Add AWS exclusion filter in generate-docs.js 🤖 - Generated by Copilot
There was a problem hiding this comment.
Pull request overview
Adds a Docusaurus 3.x documentation website intended to become the canonical Git-Ape docs site on GitHub Pages, including autogenerated docs content and CI workflows for deployment and staleness checking.
Changes:
- Introduces a new
website/Docusaurus site (config, TS setup, theme components, static assets, docs content, and sidebar structure). - Adds GitHub Actions workflows to deploy the docs site to GitHub Pages and to warn on stale generated docs in PRs.
- Updates root README and gitignore rules to link to and support the new documentation site.
Show a summary per file
| File | Description |
|---|---|
| website/tsconfig.json | Adds Docusaurus TypeScript config for IDE/typecheck support. |
| website/static/img/logo.svg | Adds SVG logo asset for the docs site. |
| website/static/img/favicon.ico | Adds favicon for the docs site. |
| website/static/img/docusaurus.png | Adds a static image asset. |
| website/static/.nojekyll | Ensures GitHub Pages doesn’t apply Jekyll processing. |
| website/src/theme/MDXComponents/index.tsx | Registers custom React components for use in MDX. |
| website/src/components/PersonaCard.tsx | Adds landing/docs UI component for persona callouts. |
| website/src/components/MetricCard.tsx | Adds landing/docs UI component for metric callouts. |
| website/src/components/FlowTimeline.tsx | Adds UI component for rendering timeline/flow steps. |
| website/src/components/FeatureGrid.tsx | Adds grid component with responsive behavior for MDX pages. |
| website/src/components/ComparisonTable.tsx | Adds side-by-side comparison table component for docs/landing. |
| website/sidebars.ts | Defines the docs navigation structure, including autogenerated sections. |
| website/package.json | Adds Docusaurus/React/TS dependencies and scripts for the website. |
| website/docusaurus.config.ts | Configures site metadata, theming, navbar/footer, Prism, and Mermaid. |
| website/docs/workflows/overview.md | Adds generated workflows overview page. |
| website/docs/workflows/git-ape-plan.md | Adds generated doc page for the plan workflow. |
| website/docs/workflows/git-ape-deploy.md | Adds generated doc page for the deploy workflow. |
| website/docs/workflows/git-ape-destroy.md | Adds generated doc page for the destroy workflow. |
| website/docs/workflows/git-ape-verify.md | Adds generated doc page for the verify workflow. |
| website/docs/workflows/git-ape-docs.md | Adds generated doc page for the docs deploy workflow. |
| website/docs/workflows/git-ape-docs-check.md | Adds generated doc page for the docs-check workflow. |
| website/docs/workflows/category.json | Adds category metadata for workflows docs section. |
| website/docs/use-cases/waf-review.md | Adds use-case documentation for WAF review. |
| website/docs/use-cases/security-analysis.md | Adds use-case documentation for the security gate. |
| website/docs/use-cases/policy-compliance.md | Adds use-case documentation for policy assessment. |
| website/docs/use-cases/multi-environment.md | Adds guidance for multi-environment strategy. |
| website/docs/use-cases/import-existing-infra.md | Adds use-case documentation for importing existing infra. |
| website/docs/use-cases/headless-mode.md | Adds documentation for headless/coding-agent mode. |
| website/docs/use-cases/drift-detection.md | Adds use-case documentation for drift detection. |
| website/docs/use-cases/deploy-web-app-sql.md | Adds use-case walkthrough for Web App + SQL. |
| website/docs/use-cases/deploy-function-app.md | Adds use-case walkthrough for Function Apps. |
| website/docs/use-cases/deploy-container-app.md | Adds use-case walkthrough for Container Apps. |
| website/docs/use-cases/cost-estimation.md | Adds use-case documentation for cost estimation. |
| website/docs/use-cases/cicd-pipeline.md | Adds CI/CD pipeline overview documentation. |
| website/docs/use-cases/category.json | Adds category metadata for use-cases section. |
| website/docs/skills/prereq-check.md | Adds generated docs for prereq-check skill. |
| website/docs/skills/overview.md | Adds generated skills inventory/overview. |
| website/docs/skills/git-ape-onboarding.md | Adds generated docs for onboarding skill. |
| website/docs/skills/azure-role-selector.md | Adds generated docs for RBAC role selection skill. |
| website/docs/skills/azure-rest-api-reference.md | Adds generated docs for REST/API reference lookup skill. |
| website/docs/skills/azure-resource-visualizer.md | Adds generated docs for resource visualizer skill. |
| website/docs/skills/azure-resource-availability.md | Adds generated docs for availability checks skill. |
| website/docs/skills/azure-naming-research.md | Adds generated docs for naming research skill. |
| website/docs/skills/azure-integration-tester.md | Adds generated docs for integration tester skill. |
| website/docs/skills/azure-deployment-preflight.md | Adds generated docs for preflight validation skill. |
| website/docs/skills/category.json | Adds category metadata for skills section. |
| website/docs/reference/plugin-json.md | Adds generated reference page for plugin.json. |
| website/docs/reference/marketplace.md | Adds generated reference page for marketplace config. |
| website/docs/reference/arm-templates.md | Adds reference page for ARM template conventions. |
| website/docs/reference/category.json | Adds category metadata for reference section. |
| website/docs/personas/for-platform-engineering.md | Adds persona docs for platform engineering audience. |
| website/docs/personas/for-executives.md | Adds persona docs for executives audience. |
| website/docs/personas/for-engineers.md | Adds persona docs for engineers audience. |
| website/docs/personas/for-engineering-leads.md | Adds persona docs for engineering leads audience. |
| website/docs/personas/for-devops.md | Adds persona docs for DevOps/SRE audience. |
| website/docs/personas/category.json | Adds category metadata for personas section. |
| website/docs/intro.md | Adds docs introduction page and entrypoint content. |
| website/docs/getting-started/installation.md | Adds installation/prerequisites docs page. |
| website/docs/getting-started/codespaces.md | Adds Codespaces/devcontainer guidance page. |
| website/docs/getting-started/azure-setup.md | Adds Azure MCP setup guidance page. |
| website/docs/getting-started/onboarding.md | Adds onboarding instructions page. |
| website/docs/getting-started/category.json | Adds category metadata for getting-started section. |
| website/docs/deployment/examples.md | Adds longer usage examples documentation. |
| website/docs/deployment/category.json | Adds category metadata for deployment docs section. |
| website/docs/changelog.md | Adds initial changelog page for docs site. |
| website/docs/agents/overview.md | Adds generated agents inventory/overview. |
| website/docs/agents/git-ape-onboarding.md | Adds generated docs for onboarding agent. |
| website/docs/agents/azure-principal-architect.md | Adds generated docs for principal architect agent. |
| website/docs/agents/azure-policy-advisor.md | Adds generated docs for policy advisor agent. |
| website/docs/agents/azure-iac-exporter.md | Adds generated docs for IaC exporter agent. |
| website/docs/agents/category.json | Adds category metadata for agents section. |
| website/README.md | Adds website contributor instructions (currently Yarn-based). |
| website/.gitignore | Adds ignore rules for Docusaurus build artifacts within website/. |
| README.md | Adds documentation site link to the root project README. |
| .gitignore | Adds root-level ignores for website build/node artifacts. |
| .github/workflows/git-ape-docs.yml | Adds workflow to build and deploy docs to GitHub Pages. |
| .github/workflows/git-ape-docs-check.yml | Adds PR workflow to detect and comment on stale generated docs. |
Copilot's findings
- Files reviewed: 86/97 changed files
- Comments generated: 11
Comment on lines
+8
to
+11
| - '.github/workflows/git-ape-plan.yml' | ||
| - '.github/workflows/git-ape-deploy.yml' | ||
| - '.github/workflows/git-ape-destroy.yml' | ||
| - '.github/workflows/git-ape-verify.yml' |
There was a problem hiding this comment.
This docs-check workflow filters on .github/workflows/git-ape-.yml, but the repo currently contains git-ape-.exampleyml (and the docs generator appears to read from those). As written, changes to the example workflows won’t trigger the stale-docs check. Update the paths filter to match the actual workflow filenames (or use a broader glob like .github/workflows/*) so the check runs when workflow sources change.
Suggested change
| - '.github/workflows/git-ape-plan.yml' | |
| - '.github/workflows/git-ape-deploy.yml' | |
| - '.github/workflows/git-ape-destroy.yml' | |
| - '.github/workflows/git-ape-verify.yml' | |
| - '.github/workflows/*' |
Comment on lines
+27
to
+33
| Validates the local environment has the CLI tools and auth sessions needed to run AutoCloud skills. | ||
|
|
||
| ## When to Use | ||
|
|
||
| - Before first-time onboarding (`/autocloud-onboarding`) | ||
| - When any AutoCloud skill fails with a "command not found" error | ||
| - When switching machines or dev containers |
There was a problem hiding this comment.
This page still uses AutoCloud terminology (AutoCloud skills, /autocloud-onboarding) even though it’s under Git-Ape docs. Please rename these references and commands to the Git-Ape equivalents to avoid confusing users.
Comment on lines
+1
to
+12
| <!-- AUTO-GENERATED — DO NOT EDIT. Source: .github/workflows/git-ape-verify.yml --> | ||
|
|
||
| --- | ||
| title: "Git-Ape: Verify Setup" | ||
| sidebar_label: "Verify Setup" | ||
| description: "GitHub Actions workflow: Git-Ape: Verify Setup" | ||
| --- | ||
|
|
||
| # Git-Ape: Verify Setup | ||
|
|
||
| **Workflow file:** `.github/workflows/git-ape-verify.yml` | ||
|
|
There was a problem hiding this comment.
This doc claims the workflow file is .github/workflows/git-ape-verify.yml, but the repo contains .github/workflows/git-ape-verify.exampleyml. Update the referenced filename (and the auto-generation source header) to match the real file so users can locate the workflow definition.
Comment on lines
+10
to
+19
| AutoCloud includes a ready-to-use [dev container](https://containers.dev/) configuration so you can start contributing or using the project instantly in GitHub Codespaces (or any dev container-compatible tool like VS Code Dev Containers). | ||
|
|
||
| ## Quick Start | ||
|
|
||
| ### Option 1: GitHub Codespaces (recommended) | ||
|
|
||
| 1. Navigate to the [AutoCloud repository](https://github.com/Azure/autocloud). | ||
| 2. Click **Code** → **Codespaces** → **Create codespace on main**. | ||
| 3. Wait for the container to build and the post-create setup to finish. | ||
| 4. Sign in to Azure with `az login` when prompted. |
There was a problem hiding this comment.
This page references “AutoCloud” and links to the Azure/autocloud repo, which doesn’t match this project (Git-Ape). Update the product name, repository link, and the example command (currently @autocloud) to Git-Ape so users aren’t sent to the wrong project.
| winget install jqlang.jq | ||
| ``` | ||
|
|
||
| > **Note:** AutoCloud skills require a BASH shell. Install [Git for Windows](https://gitforwindows.org/) and use git-bash. |
There was a problem hiding this comment.
This onboarding doc references “AutoCloud skills” (project name mismatch). Update to “Git-Ape” (and any related command names) to keep the getting-started flow consistent.
Suggested change
| > **Note:** AutoCloud skills require a BASH shell. Install [Git for Windows](https://gitforwindows.org/) and use git-bash. | |
| > **Note:** Git-Ape commands require a Bash shell. Install [Git for Windows](https://gitforwindows.org/) and use Git Bash. |
Comment on lines
+1
to
+12
| <!-- AUTO-GENERATED — DO NOT EDIT. Source: .github/workflows/git-ape-plan.yml --> | ||
|
|
||
| --- | ||
| title: "Git-Ape: Plan" | ||
| sidebar_label: "Plan" | ||
| description: "GitHub Actions workflow: Git-Ape: Plan" | ||
| --- | ||
|
|
||
| # Git-Ape: Plan | ||
|
|
||
| **Workflow file:** `.github/workflows/git-ape-plan.yml` | ||
|
|
There was a problem hiding this comment.
This doc claims the workflow file is .github/workflows/git-ape-plan.yml, but the repo contains .github/workflows/git-ape-plan.exampleyml. Update the referenced filename (and the auto-generation source header) to match the real file so users can locate the workflow definition.
Comment on lines
+7
to
+23
| ```bash | ||
| yarn | ||
| ``` | ||
|
|
||
| ## Local Development | ||
|
|
||
| ```bash | ||
| yarn start | ||
| ``` | ||
|
|
||
| This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. | ||
|
|
||
| ## Build | ||
|
|
||
| ```bash | ||
| yarn build | ||
| ``` |
There was a problem hiding this comment.
website/package.json and the GitHub Actions workflows use npm (npm ci / npm run build), but this README documents Yarn commands. Update the commands to npm equivalents or add/commit the required Yarn artifacts (e.g., yarn.lock) and align CI to Yarn so local instructions match what CI runs.
Comment on lines
+16
to
+21
| | Workflow | File | Triggers | Jobs | | ||
| |----------|------|----------|------| | ||
| | [Git-Ape: Deploy](./git-ape-deploy) | `git-ape-deploy.yml` | push, issue_comment | check-comment-trigger, detect-deployments, deploy | | ||
| | [Git-Ape: Destroy](./git-ape-destroy) | `git-ape-destroy.yml` | push, workflow_dispatch | detect-destroys, destroy | | ||
| | [Git-Ape: Plan](./git-ape-plan) | `git-ape-plan.yml` | pull_request | detect-deployments, plan-local, plan-azure, plan-comment | | ||
| | [Git-Ape: Verify Setup](./git-ape-verify) | `git-ape-verify.yml` | workflow_dispatch | verify | |
There was a problem hiding this comment.
The workflow inventory lists git-ape--.yml files, but the repository currently contains git-ape-*.exampleyml (plus the docs workflows). Either rename/ship the real .yml workflows or update this table to reflect the actual filenames so the docs match what exists in .github/workflows/.
Comment on lines
+1
to
+12
| <!-- AUTO-GENERATED — DO NOT EDIT. Source: .github/workflows/git-ape-deploy.yml --> | ||
|
|
||
| --- | ||
| title: "Git-Ape: Deploy" | ||
| sidebar_label: "Deploy" | ||
| description: "GitHub Actions workflow: Git-Ape: Deploy" | ||
| --- | ||
|
|
||
| # Git-Ape: Deploy | ||
|
|
||
| **Workflow file:** `.github/workflows/git-ape-deploy.yml` | ||
|
|
There was a problem hiding this comment.
This doc claims the workflow file is .github/workflows/git-ape-deploy.yml, but the repo contains .github/workflows/git-ape-deploy.exampleyml. Update the referenced filename (and the auto-generation source header) to match the real file so users can locate the workflow definition.
Comment on lines
+1
to
+12
| <!-- AUTO-GENERATED — DO NOT EDIT. Source: .github/workflows/git-ape-destroy.yml --> | ||
|
|
||
| --- | ||
| title: "Git-Ape: Destroy" | ||
| sidebar_label: "Destroy" | ||
| description: "GitHub Actions workflow: Git-Ape: Destroy" | ||
| --- | ||
|
|
||
| # Git-Ape: Destroy | ||
|
|
||
| **Workflow file:** `.github/workflows/git-ape-destroy.yml` | ||
|
|
There was a problem hiding this comment.
This doc claims the workflow file is .github/workflows/git-ape-destroy.yml, but the repo contains .github/workflows/git-ape-destroy.exampleyml. Update the referenced filename (and the auto-generation source header) to match the real file so users can locate the workflow definition.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add full Docusaurus 3.x documentation website to serve as the canonical production docs at azure.github.io/git-ape.
What's included
scripts/generate-docs.jsgit-ape-docs.yml— deploys to GitHub Pages on push to maingit-ape-docs-check.yml— PR check for stale generated docsPath updates
All references to
git-ape-privatehave been updated togit-apeacross:docusaurus.config.ts(baseUrl, projectName, editUrl, navbar, footer links)Post-merge action required
After merging, an admin needs to set the GitHub Pages source to GitHub Actions (Settings → Pages → Source → GitHub Actions) for the deployment workflow to work.
Related
🤖 - Generated by Copilot