Update workshop content and publishing process#140
Open
GeekTrainer wants to merge 29 commits intomainfrom
Open
Update workshop content and publishing process#140GeekTrainer wants to merge 29 commits intomainfrom
GeekTrainer wants to merge 29 commits intomainfrom
Conversation
Agent-Logs-Url: https://github.com/github-samples/agents-in-sdlc/sessions/fe23a7c4-299e-4150-9215-ce55e8e0682e Co-authored-by: GeekTrainer <6109729+GeekTrainer@users.noreply.github.com>
…de, Cloud, Complete) Agent-Logs-Url: https://github.com/github-samples/agents-in-sdlc/sessions/fe23a7c4-299e-4150-9215-ce55e8e0682e Co-authored-by: GeekTrainer <6109729+GeekTrainer@users.noreply.github.com>
Agent-Logs-Url: https://github.com/github-samples/agents-in-sdlc/sessions/fe23a7c4-299e-4150-9215-ce55e8e0682e Co-authored-by: GeekTrainer <6109729+GeekTrainer@users.noreply.github.com>
Builds out the workshop-content/ directory as a publishable MkDocs site
and removes long-standing duplication across the three learning paths.
Site infrastructure (Phase A1)
- mkdocs.yml at repo root with Material theme, dark/light toggle,
nav tabs, search, code-copy, edit links, and PyMdown Snippets
configured against partials/.
- requirements-docs.txt pinning mkdocs-material, pymdown-extensions,
and mkdocs-callouts (renders > [!NOTE]/[!IMPORTANT]/[!TIP] blocks
as Material admonitions).
- .github/workflows/pages.yml builds with mkdocs --strict on PRs
(validation only) and on push to main (build + deploy via
actions/deploy-pages). Explicit per-job permissions; pages
concurrency group; pinned actions.
- site/ and .venv-docs/ added to .gitignore.
Content partials (Phase A2 — Tier 1)
Five reusable snippets at repo-root partials/, replacing verbatim
duplicates across paths via --8<-- includes:
- sections/coding-agent-intro.md (vscode/4 + cloud/2)
- sections/iterating-recap.md (vscode/7 + cloud/5)
- sections/security-coding-agent.md (vscode/7 + cloud/5)
- scenarios/tech-debt.md (vscode/4 + cloud/2)
- scenarios/accessibility.md (cli/6 + shared/coding-agent/custom-agents)
Partials follow inline-links-only / no-images / no-H1 rules
documented in partials/README.md.
Path-publishing fixes
- Converted 3 outbound links pointing to .github/instructions/*.md
to absolute github.com URLs (would otherwise break --strict).
- Escaped <branch-name> placeholders in iterating files so they
render as code spans, not stray HTML tags.
- Escaping shared/1 link refs to absolute URLs preserves both raw
GitHub readability and Pages strict build.
Prior dedup + cleanup (also pending on this branch, included here)
- shared/coding-agent/{custom-agents,managing-agents}.md as
canonical bodies for the cross-path coding-agent flows.
- Wrappers in vscode/{5,6} and cloud/{3,4} reduced to skeletons
pointing to the shared module.
- Multiple polish passes from earlier session work
(cli warm-up, hands-on demos, /delegate optional section, etc.).
Local validation: mkdocs build --strict passes with zero errors;
all 5 partials resolve correctly in rendered output; GitHub alerts
render as Material admonitions.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace the MkDocs Material build (and the opaque PyMdown --8<-- snippet syntax) with a new Astro + Starlight project under docs/. Authored content stays in workshop-content/ and is loaded via Astro's glob() loader. - New docs/ project with Astro 5 + Starlight 0.36, separate from client/ - Convert all Markdown to .mdx with YAML frontmatter - Replace --8<-- snippet includes with MDX partials in workshop-content/_partials/ and typed Astro components in docs/src/components/ (CalloutCloudAgentRequired, PrereqCopilotBase) - Convert GitHub-style alerts (> [!NOTE], etc.) to Starlight <Aside> - Drop manual prev/next tables; Starlight generates them from sidebar order - Rename README.md -> index.mdx so directory URLs stay stable - Rewrite internal .md links to relative directory-style route URLs so they work under the /agents-in-sdlc/ base path - Rewrite .github/workflows/pages.yml for Node + Astro + lychee link check - Symlink workshop-content/node_modules -> ../docs/node_modules so MDX outside docs/ can resolve @astrojs/starlight/components - Delete mkdocs.yml, requirements-docs.txt, partials/, site/ - Update root README.md to describe the new docs build Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Previously it lived as a standalone top-level sidebar entry (mirroring the old mkdocs nav). Each course should treat custom instructions as its own module 1, so add it inside the VS Code, CLI, and Cloud agent path groups. The destination URL still points at the shared page under /shared/1-custom-instructions/. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Each path now has its own hands-on module that walks through the 'add a docstring requirement to copilot-instructions.md and watch the output change' exercise from main, using the path's actual tool: - vscode/2-custom-instructions.mdx (was a stub) — full Copilot Chat walkthrough - cli/3-custom-instructions.mdx (new) — same exercise driven by Copilot CLI - _partials/instructions-add-docstring.mdx — shared steps for the copilot-instructions.md edit, imported by both pages CLI path is renumbered so install precedes the new hands-on: 3-mcp -> 4-mcp, 4-generating-code -> 5-generating-code, 5-agent-skills -> 6-agent-skills, 6-custom-agents -> 7-custom-agents, 7-slash-commands -> 8-slash-commands, 8-review -> 9-review. Sidebar, prev/next chains, and cross-path index tables updated to match. Fixes vscode prev/next refs that the bulk renumber sed accidentally shifted (vscode/3-mcp, 6-custom-agents are unchanged). Build: 28 pages. Lychee: 0 errors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Each learning path now owns its own module 1 covering custom instructions: - VS Code: read + update + see impact via Copilot Chat - CLI: install (1) then read + update + see impact via copilot CLI (2) - Cloud agent: read + update only (impact shown later in cloud agent PRs) Removed the shared lesson at shared/1-custom-instructions.mdx since each path's coverage differs slightly. The shared overview content is now in _partials/instructions-overview.mdx, imported into each path's module 1. The shared prerequisites lesson now branches into the three paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- cli/2-custom-instructions: stop deleting publishers.py between rounds. Round 2 now asks Copilot to update the existing file to match the new documentation conventions, and learners leave the file in place. - cli/4-generating-code: remove the redundant 'Warm-up: see custom instructions in action' section. That demo now lives entirely in module 2, so the generating-code lesson goes straight into plan mode. - cli/4-generating-code: add a security caution around copilot --allow-all-tools, sourced from the GitHub Copilot CLI docs on allowing/denying tool use. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace repeated 'return to your codespace / open terminal / run copilot' preambles with a single <Aside type="tip"> callout at the top of each lesson page. Three partials cover: basic CLI, allow-all CLI (with link to the full warning in 4-generating-code.mdx), and VS Code Chat. CLI callouts mention 'copilot --continue' for resuming the most recent session in the current project. Also dedupes a duplicate mode/model selection block in vscode/3-agent-mode.mdx and moves the long --allow-all-tools caution in cli/4-generating-code.mdx out of step 3 into a standalone caution above the step list. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Previously placed at the top of each lesson page (in the conceptual intro area), the Start a Copilot CLI/Chat callouts now sit immediately under the heading of the first exercise where the learner actually opens Copilot. This keeps the callout adjacent to where its instructions are needed, instead of being separated from the action by scenario, objectives, and concept sections. Affected pages: - vscode/2-mcp.mdx -> '### Examine the impact of custom instructions' - cli/3-mcp.mdx -> '## Setting up the GitHub MCP server in Copilot CLI' - cli/4-generating-code.mdx -> '## Utilize plan mode' - cli/5-agent-skills.mdx -> '## Using the skill' - cli/6-custom-agents.mdx -> '## Using a custom agent in Copilot CLI' - cli/7-slash-commands.mdx -> '## Sharing a session' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…upes Partials now follow a category-prefix scheme so role-in-lesson is visible at a glance: - callout-* for Aside/Tip blocks - section-* for top-level concept blocks - exercise-* for mid-lesson step inserts Filename pattern is <category>-<topic>.mdx; component symbols are PascalCase of the topic portion only, keeping lesson source readable (<StartCopilotCli />, <CloudAgentIntro />). Renamed all 10 existing partials and updated imports across 15 lesson files. While touching imports, also corrected two pre-existing component-name drifts (CodingAgentIntro -> CloudAgentIntro, SecurityCodingAgent -> CloudAgentSecurity) and made scenario-block filenames self-describing (accessibility -> section-accessibility-scenario, tech-debt -> section-tech-debt-scenarios). New shared partials: - callout-model-choice-caution.mdx — adopted in vscode/2-mcp and vscode/3-agent-mode (one-word 'lab' vs 'workshop' drift now fixed). - section-mcp-overview.mdx — adopted in cli/3-mcp and vscode/2-mcp. Uses inline links so it's self-contained when imported. Diagram and agent-mode framing paragraph stay in vscode/2 (VS-Code-specific). Bug cleanups found during review: - vscode/2-mcp.mdx had 'Ensure your codespace is ready' twice (H3 at line 14 and H2 at line 124). Kept the H3 occurrence; removed the H2 duplicate that ran after the learner had already done the steps. - vscode/4-cloud-agent.mdx had '## Summary and next steps' twice. Removed the stray early summary heading and its single paragraph; kept the full summary section that follows. Build clean (28 pages); lychee 1694/0. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
cloud/2-cloud-agent.mdx and vscode/4-cloud-agent.mdx were ~95%
identical (190 lines each, only 11 lines + frontmatter + ref paths
differed). Apply the same redirect-stub pattern already used for
custom-agents and managing-agents.
Changes:
- New shared/cloud-agent/cloud-agent.mdx: full lesson body taken from
the cloud/2 version (the superset). Image and partial paths shifted
one level deeper.
- The cloud-only 'Custom instructions in this repository' section is
kept unconditionally, with a one-sentence softening so it reads for
both audiences (vscode learners get a quick reinforcement;
cloud learners get the same pointer they had before).
- 'Return to your path' footer at the end mirroring the existing
shared modules.
- cloud/2-cloud-agent.mdx and vscode/4-cloud-agent.mdx are now
~15-line redirect stubs.
Pre-existing bug fix folded in: both source files had a duplicated
step 9 ('Select **Assign**.' appeared once before and once after the
eyes-emoji image in the second issue-assignment list). Dropped the
stray second occurrence in the shared body.
Build clean (29 pages); lychee 1709/0.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replaces the app-development Copilot configuration with a content-focused playbook now that the Tailspin Toys application has been extracted to github.com/github-samples/tailspin-toys. - Rewrite .github/copilot-instructions.md as the content-author core: scope, repo structure, partials prefix conventions (callout-/section-/ exercise-), shared-module redirect-stub pattern, link patterns, build + lychee verification, commit hygiene. - Add scoped instruction files with applyTo frontmatter: - mdx.instructions.md (workshop MDX patterns) - markdown.instructions.md (no hard-wrap; GitHub admonitions) - partials.instructions.md (naming + self-contained refs) - astro.instructions.md (docs/ wrapper conventions) - Delete .github/agents/accessibility.md (app-focused custom agent). - Delete the seven app-targeted files in .github/instructions/ (astro, flask-endpoint, playwright, python-tests, svelte, tailwindcss, ui). Atomic with the deletes so no intermediate state still tells agents to use the deleted Flask/Svelte/Tailwind guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The Flask + Astro/Svelte demo application has been extracted to
github.com/github-samples/tailspin-toys. This repo is now a content-only
authoring repo for the workshop.
Removed:
- client/, server/, data/ — application source and SQLite seed
- scripts/{setup-env,start-app,run-server-tests}.sh — app dev scripts
- venv/, .venv-docs/ — local virtualenvs
- .devcontainer/, .vscode/ — app-targeted dev environment config
- .github/workflows/copilot-setup-steps.yml — app cloud-agent setup
- .github/workflows/run-tests.yml — app test workflow
Updated:
- .gitignore: pruned Python/Flask/SQLite/devcontainer entries; kept
workshop-content/node_modules (still needed for the symlink that
pages.yml creates so MDX outside docs/ can resolve Starlight imports).
- .github/dependabot.yml: rescoped from /client + devcontainers to /docs.
Only pages.yml remains under .github/workflows/ — the workshop site
deployment is unchanged.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Both READMEs were app-aware (mentions of client/, scripts/start-app.sh, the Tailspin Toys app description). Refocus them on workshop content authoring now that the application lives at github-samples/tailspin-toys. - Root README: scope, repo structure, local dev (with the workshop-content/node_modules symlink step), verification commands, pointers to authoring instructions and the tailspin-toys app repo. - docs/README: drop client/ cross-reference; describe docs/ as the thin Astro+Starlight wrapper around workshop-content/. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Imported from github/awesome-copilot@65b20ad. Skills (.github/skills/): - create-github-pull-request-from-specification — explicitly requested. Adds .github/pull_request_template.md (the skill expects one) tailored to this repo's verification flow (build target + lychee). - publish-to-pages — full directory including companion scripts (convert-pdf.py, convert-pptx.py, publish.sh). Also adds a local README clarifying that this skill is for spinning up a *separate* Pages site (e.g., a slide deck), NOT the deployment for this repo's workshop site (that's pages.yml). - conventional-commit — commit message hygiene. - update-markdown-file-index — keeps file-index sections in markdown files in sync with their folders. Agents (.github/agents/): - se-technical-writer — technical writing assistant. - technical-content-evaluator — A-grade content quality eval. - markdown-accessibility-assistant — five GitHub a11y best practices. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ilspin-toys The Tailspin Toys application learners build through has moved to github.com/github-samples/tailspin-toys. Update workshop content to point there instead of the (now content-only) agents-in-sdlc repo. - shared/0-prereqs.mdx: 'Use this template' instructions now point at github-samples/tailspin-toys. - _partials/section-instructions-overview.mdx: ui-instructions and astro-instructions ref definitions now point at the tailspin-toys copies of those files. - vscode/3-agent-mode.mdx: same UI instructions URL update. Verified: docs build still produces 29 pages; lychee link check passes (1460 OK, 0 errors). Note for maintainers: github-samples/tailspin-toys is currently INTERNAL — it must be made public (or the workshop run inside the github-samples org) before learners can fork it from the template. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds scripts/render-markdown.py — a stdlib-only Python renderer that converts workshop-content/**/*.mdx into plain GitHub-flavored Markdown under workshop/. Two-pass design separates partial-inlining (file-relative context) from link rewriting (URL-relative to importer). Stack-based <Aside> parser handles nesting; admonitions wrap every body line including code-fence delimiters with '> '. Stub pages are detected structurally and shared content is inlined with a synthesized prev/next footer. All unresolved partials, components, links, and images hard-fail. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds the rendered workshop/ output: 27 lesson Markdown files + 4 path README.md indexes + a copy of workshop-content/images/. Generated from workshop-content/ by scripts/render-markdown.py. Marked as linguist-generated via .gitattributes so it doesn't dominate language stats or PR diffs. Learners can now take the workshop directly on GitHub.com via workshop/README.md without visiting the published Pages site or running any tooling locally. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds .github/workflows/render-markdown.yml. On every PR that touches workshop-content/, workshop/, the renderer, or the workflow itself: re-runs scripts/render-markdown.py, fails on `git diff --exit-code workshop/` if the committed output is stale, then runs lychee against workshop/**/*.md as a second gate to catch broken-but-self-consistent link rewrites. Permissions: contents: read. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- README: top section now sends learners to workshop/README.md (the GitHub.com-readable view) alongside the published Pages site, with an explicit warning not to edit workshop/ by hand. Adds the render step to the pre-PR verification checklist. - copilot-instructions.md: documents the render pipeline. When editing anything under workshop-content/, run `python scripts/render-markdown.py` and commit the resulting workshop/ changes in the same PR. CI rejects drift. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Flips the render-markdown workflow from a verify-on-PR gate to a generate- on-main pattern. - On pull_request: run the renderer as a hard-fail validation gate (catches missing partials, unresolved components, broken internal links, missing images), plus lychee on the rendered output. Does not commit. - On push to main: regenerate workshop/ and commit any diff back to main as github-actions[bot] with [skip ci] in the message to avoid recursion. pages.yml watches workshop-content/** and docs/**, not workshop/**, so it also will not re-fire on the bot commit. Authors no longer need to commit workshop/ alongside workshop-content/ edits — the bot owns that folder. The local renderer script (scripts/render-markdown.py) remains for previewing if desired but running it is optional. If branch protection on main blocks bot pushes, options: configure bypass for github-actions[bot], use a PAT with bypass, or switch to bot-PR pattern. Will surface on first merge after this change. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ance - Add AUTHORING.md as the author entry point: mental model, recipe-style step-by-steps for adding lessons / partials / images / edits, local preview, style essentials, CI expectations, troubleshooting. - Rewrite CONTRIBUTING.md as a short pointer (drops Go / golangci-lint boilerplate inherited from a template repo). - Fix astro.instructions.md: sidebar is manually maintained in astro.config.mjs, not auto-generated. Remove now-obsolete guidance about node_modules symlinks (next commit moves content into docs/). Path references in these files describe the post-migration layout (docs/src/content/docs/); the next commit makes that layout real. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Eliminates the workshop/ <-> workshop-content/ name collision at the repo root and removes the workshop-content/node_modules symlink hack. Lesson MDX now lives at Astro's standard content-collection location, so packages resolve natively from docs/node_modules. Mechanics: - git mv workshop-content -> docs/src/content/docs - content.config.ts: shorten loader base to 'src/content.docs'. Custom glob() loader is retained because Starlight's default docsLoader() only excludes underscore-prefixed *filenames*, not *directories*; without the custom loader, _partials/* would route as pages. - astro.config.mjs: editLink.baseUrl -> .../edit/main/docs/. Starlight appends entry.filePath (project-rooted, e.g. src/content/docs/...), so the resulting edit URL is correct with no doubled segments. - scripts/render-markdown.py: SOURCE_DIR + banner + docstrings + comments + error messages all updated. - pages.yml: drop the now-impossible 'Link node_modules into workshop-content' step (parent dir no longer exists post-move). paths filter narrowed to docs/**. - render-markdown.yml: paths filter -> docs/src/content/docs/**; bot commit message references the new path. - copilot-instructions.md, partials.instructions.md, markdown.instructions.md, README.md, docs/README.md: all path references updated. - .gitignore: drop workshop-content/node_modules entry (no symlink). - workshop/: regenerated. Diff is banner-only (Source: line). Verified: - python scripts/render-markdown.py -> banner-only diff - cd docs && npm run build -> 29 pages (no _partials routed) - Edit-this-page link sample: .../edit/main/docs/src/content/docs/... (no doubled path segments) - lychee --offline 'workshop/**/*.md' -> 195 OK / 0 errors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Covers __pycache__/, compiled bytecode, pytest/mypy/ruff caches, and common venv directories. The renderer script under scripts/ produces __pycache__/ on every local run. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
GeekTrainer
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refactors the repository from a mixed “workshop content + Tailspin Toys demo app” layout into a workshop-content-only repo: MDX source is relocated into Starlight’s conventional docs/src/content/docs/ tree, the generated GitHub-readable mirror remains under workshop/, and the authoring/contribution docs + CI workflows are updated accordingly.
Changes:
- Move workshop MDX source into
docs/src/content/docs/and regenerate theworkshop/Markdown mirror with updated banners/paths. - Add/refresh author-facing repo docs (README + CONTRIBUTING) and add Starlight site scaffolding/config under
docs/. - Replace CI with focused
pages.yml(build/link-check/deploy) andrender-markdown.yml(render/link-check + bot regeneration onmain), plus housekeeping updates (.gitignore, dependabot, etc.).
Show a summary per file
| File | Description |
|---|---|
| workshop/vscode/README.md | Generated VS Code path README |
| workshop/vscode/6-managing-agents.md | Generated lesson output |
| workshop/vscode/5-custom-agents.md | Generated lesson output |
| workshop/shared/cloud-agent/managing-agents.md | Generated shared module output |
| workshop/shared/cloud-agent/custom-agents.md | Generated shared module output |
| workshop/shared/0-prereqs.md | Generated prerequisites output |
| workshop/README.md | Generated workshop entry README |
| workshop/cloud/README.md | Generated cloud path README |
| workshop/cloud/4-managing-agents.md | Generated lesson output |
| workshop/cloud/3-custom-agents.md | Generated lesson output |
| workshop/cli/README.md | Generated CLI path README |
| workshop/cli/8-review.md | Generated lesson output |
| workshop/cli/1-install-copilot-cli.md | Generated lesson output |
| workshop-content/README.md | Removed old content root README |
| server/utils/seed_database.py | Removed demo app script |
| server/utils/seed_data/games.csv | Removed demo app seed data |
| server/utils/database.py | Removed demo app DB helper |
| server/utils/init.py | Removed demo app package marker |
| server/tests/test_models.py | Removed demo app tests |
| server/tests/init.py | Removed demo app package marker |
| server/routes/games.py | Removed demo app API routes |
| server/routes/init.py | Removed demo app package marker |
| server/requirements.txt | Removed demo app deps file |
| server/models/publisher.py | Removed demo app model |
| server/models/game.py | Removed demo app model |
| server/models/category.py | Removed demo app model |
| server/models/base.py | Removed demo app model base |
| server/models/init.py | Removed demo app model init |
| server/app.py | Removed demo app server entry |
| server/init.py | Removed demo app package marker |
| scripts/start-app.sh | Removed demo app start script |
| scripts/setup-env.sh | Removed demo app env setup |
| scripts/run-server-tests.sh | Removed demo app test script |
| README.md | Rewrite to workshop-content-only README |
| docs/tsconfig.json | Add docs-site TS config |
| docs/src/content/docs/vscode/index.mdx | Add VS Code path landing page |
| docs/src/content/docs/vscode/images/.gitkeep | Track images dir |
| docs/src/content/docs/vscode/6-managing-agents.mdx | Add VS Code stub to shared module |
| docs/src/content/docs/vscode/5-custom-agents.mdx | Add VS Code stub to shared module |
| docs/src/content/docs/vscode/4-cloud-agent.mdx | Add VS Code stub to shared module |
| docs/src/content/docs/shared/images/.gitkeep | Track shared images dir |
| docs/src/content/docs/shared/cloud-agent/managing-agents.mdx | Add shared module source |
| docs/src/content/docs/shared/cloud-agent/custom-agents.mdx | Add shared module source |
| docs/src/content/docs/shared/0-prereqs.mdx | Add shared prerequisites source |
| docs/src/content/docs/index.mdx | Add site home content |
| docs/src/content/docs/cloud/index.mdx | Add cloud path landing page |
| docs/src/content/docs/cloud/images/.gitkeep | Track images dir |
| docs/src/content/docs/cloud/4-managing-agents.mdx | Add cloud stub to shared module |
| docs/src/content/docs/cloud/3-custom-agents.mdx | Add cloud stub to shared module |
| docs/src/content/docs/cloud/2-cloud-agent.mdx | Add cloud stub to shared module |
| docs/src/content/docs/cloud/1-custom-instructions.mdx | Add cloud path lesson source |
| docs/src/content/docs/cli/index.mdx | Add CLI path landing page |
| docs/src/content/docs/cli/images/.gitkeep | Track images dir |
| docs/src/content/docs/cli/8-review.mdx | Add CLI lesson source |
| docs/src/content/docs/cli/6-custom-agents.mdx | Add CLI lesson source |
| docs/src/content/docs/cli/5-agent-skills.mdx | Add CLI lesson source |
| docs/src/content/docs/cli/4-generating-code.mdx | Add CLI lesson source |
| docs/src/content/docs/cli/3-mcp.mdx | Add CLI lesson source |
| docs/src/content/docs/cli/1-install-copilot-cli.mdx | Add CLI lesson source |
| docs/src/content/docs/_partials/section-tech-debt-scenarios.mdx | Add reusable scenario partial |
| docs/src/content/docs/_partials/section-mcp-overview.mdx | Add reusable MCP overview partial |
| docs/src/content/docs/_partials/section-iterating-recap.mdx | Add reusable recap partial |
| docs/src/content/docs/_partials/section-instructions-overview.mdx | Add reusable instructions partial |
| docs/src/content/docs/_partials/section-cloud-agent-security.mdx | Add reusable security partial |
| docs/src/content/docs/_partials/section-cloud-agent-intro.mdx | Add reusable intro partial |
| docs/src/content/docs/_partials/section-accessibility-scenario.mdx | Add reusable scenario partial |
| docs/src/content/docs/_partials/exercise-instructions-add-docstring.mdx | Add reusable exercise partial |
| docs/src/content/docs/_partials/callout-start-copilot-cli.mdx | Add reusable callout partial |
| docs/src/content/docs/_partials/callout-start-copilot-cli-allow-all.mdx | Add reusable callout partial |
| docs/src/content/docs/_partials/callout-start-copilot-chat.mdx | Add reusable callout partial |
| docs/src/content/docs/_partials/callout-model-choice-caution.mdx | Add reusable callout partial |
| docs/src/content.config.ts | Configure docs collection loader |
| docs/src/components/PrereqCopilotBase.astro | Add docs component (prereq snippet) |
| docs/src/components/CalloutCloudAgentRequired.astro | Add docs component (callout) |
| docs/README.md | Add docs-site README |
| docs/public/favicon.svg | Add docs-site favicon |
| docs/package.json | Add docs-site dependencies/scripts |
| docs/astro.config.mjs | Add Starlight site config/sidebar |
| docs/.gitignore | Add docs-site ignores |
| CONTRIBUTING.md | Rewrite contributing guide |
| client/tsconfig.json | Remove demo app client config |
| client/svelte.config.js | Remove demo app client config |
| client/src/styles/global.css | Remove demo app styling |
| client/src/pages/index.astro | Remove demo app page |
| client/src/pages/game/[id].astro | Remove demo app page |
| client/src/pages/about.astro | Remove demo app page |
| client/src/middleware.ts | Remove demo app middleware |
| client/src/layouts/Layout.astro | Remove demo app layout |
| client/src/components/LoadingSkeleton.svelte | Remove demo app component |
| client/src/components/Header.astro | Remove demo app component |
| client/src/components/GameList.svelte | Remove demo app component |
| client/src/components/GameDetails.svelte | Remove demo app component |
| client/src/components/GameCard.svelte | Remove demo app component |
| client/src/components/ErrorMessage.svelte | Remove demo app component |
| client/src/components/EmptyState.svelte | Remove demo app component |
| client/src/assets/background.svg | Remove demo app asset |
| client/README.md | Remove demo app README |
| client/public/favicon.svg | Remove demo app favicon |
| client/playwright.config.ts | Remove demo app test config |
| client/package.json | Remove demo app deps/scripts |
| client/e2e-tests/home.spec.ts | Remove demo app e2e tests |
| client/e2e-tests/games.spec.ts | Remove demo app e2e tests |
| client/Dockerfile | Remove demo app Dockerfile |
| client/astro.config.mjs | Remove demo app Astro config |
| client/.gitignore | Remove demo app ignore |
| client/.dockerignore | Remove demo app ignore |
| .vscode/settings.json | Remove editor settings |
| .vscode/mcp.json | Remove repo MCP config |
| .vscode/.copilotignore | Remove old Copilot ignore |
| .gitignore | Update ignore rules (Python + docs) |
| .github/workflows/run-tests.yml | Remove demo app CI workflow |
| .github/workflows/render-markdown.yml | Add MDX→workshop render workflow |
| .github/workflows/pages.yml | Add docs-site build/deploy workflow |
| .github/workflows/copilot-setup-steps.yml | Remove demo setup workflow |
| .github/skills/update-markdown-file-index/SKILL.md | Add skill definition |
| .github/skills/publish-to-pages/SKILL.md | Add skill definition |
| .github/skills/publish-to-pages/scripts/publish.sh | Add publish helper script |
| .github/skills/publish-to-pages/README.md | Add skill README |
| .github/skills/create-github-pull-request-from-specification/SKILL.md | Add skill definition |
| .github/skills/conventional-commit/SKILL.md | Add skill definition |
| .github/pull_request_template.md | Add PR template |
| .github/instructions/ui.instructions.md | Remove old UI instructions |
| .github/instructions/tailwindcss.instructions.md | Remove old Tailwind instructions |
| .github/instructions/svelte.instructions.md | Remove old Svelte instructions |
| .github/instructions/python-tests.instructions.md | Remove old Python test instructions |
| .github/instructions/playwright.instructions.md | Remove old Playwright instructions |
| .github/instructions/partials.instructions.md | Add partials authoring conventions |
| .github/instructions/mdx.instructions.md | Add MDX authoring conventions |
| .github/instructions/markdown.instructions.md | Add repo markdown conventions |
| .github/instructions/flask-endpoint.instructions.md | Remove old Flask instructions |
| .github/instructions/astro.instructions.md | Update Astro/Starlight wrapper guidance |
| .github/dependabot.yml | Point dependabot to docs/ |
| .gitattributes | Mark workshop output as generated |
| .devcontainer/devcontainer.json | Remove devcontainer config |
Copilot's findings
Comments suppressed due to low confidence (1)
docs/src/content/docs/cli/1-install-copilot-cli.mdx:110
- The “Summary and next steps” sentence references “Exercise 3 - Custom instructions”, but the
next-lessonlink points to../2-custom-instructions/and the CLI path overview lists Custom instructions as Exercise 2. Update the text to match the correct exercise number/title.
- Files reviewed: 160/257 changed files
- Comments generated: 3
Comment on lines
+1
to
+3
| --- | ||
| title: "Exercise 2 - Installing GitHub Copilot CLI" | ||
| --- |
Comment on lines
+48
to
+50
| ## No `<Aside>` imports inside callout partials | ||
|
|
||
| When the partial *is* a single `<Aside>`, the import for `Aside` lives in the host MDX page. The partial just contains the JSX. (Imports inside partials are allowed but the convention is to keep partials minimal.) |
Comment on lines
+26
to
+28
| permissions: | ||
| contents: write # required to push the regenerated workshop/ back to main | ||
|
|
…practice - cli/1-install-copilot-cli.mdx: title was 'Exercise 2' and the next-lesson sentence pointed to 'Exercise 3'. The CLI overview correctly lists this lesson as Exercise 1 and the next as Exercise 2. Renumber both. Workshop/ regenerated to match. - partials.instructions.md: previous guidance said callout partials must NOT import Aside (host page imports it). Every existing callout-*.mdx contradicts this — they all import Aside themselves. Reverse the guidance to match practice: callout partials are self-contained and import their own Starlight components. Both findings surfaced in Copilot's PR review on #140. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Pin lycheeverse/lychee-action from the floating @v2 tag to commit SHA 8646ba30535128ac92d33dfc9133794bfdd9b411 (v2.6.1) in both pages.yml and render-markdown.yml. Resolves CodeQL findings about unpinned third-party actions on PR #140. - Split render-markdown.yml into a 'validate' job (contents: read, runs on every event) and a 'commit' job (contents: write, runs only on push to main, depends on validate). Previously the workflow granted contents: write at the workflow level, which also applied to PR runs even though those never push. Now PR runs execute with read-only contents permission, matching least-privilege guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
This branch repositions the repo from "Tailspin Toys app + workshop content side-by-side" to a content-only workshop repository with a modern Astro + Starlight site, an auto-generated GitHub.com-readable Markdown mirror, validated CI, and a clear on-ramp for content authors. The Tailspin Toys application code now lives in
github-samples/tailspin-toys; this repo holds only the lessons, the site that publishes them, and the automation that keeps both views in sync.Why
Before this branch:
CONTRIBUTING.mdwas Go template boilerplate.After this branch: a focused content repo with two synchronized views (site + on-GitHub Markdown), a multi-path lesson layout with shared modules, a partials system, and clear author docs.
What changed
1. Repo refocus — content only
client/,server/,scripts/setup-env.sh,scripts/start-app.sh,scripts/run-server-tests.sh,data/tailspin-toys.db,.devcontainer/,client/Dockerfile, app-only workflows). The app now lives atgithub-samples/tailspin-toys..github/copilot-instructions.md, deletes app-specific instructions (flask-endpoint,playwright,python-tests,svelte,tailwindcss,ui), keeps only what authors need.github/awesome-copilot:markdown-accessibility-assistant,se-technical-writer,technical-content-evaluatoragents;conventional-commit,create-github-pull-request-from-specification,publish-to-pages,update-markdown-file-indexskills.github.com/github-samples/tailspin-toys/....2. Workshop site — MkDocs → Astro + Starlight
docs/Astro + Starlight project with manually maintained sidebar, content-collection-driven pages, dark theme, search via Pagefind.glob()content loader excludes underscore-prefixed directories (Starlight's default only excludes underscore-prefixed filenames) so_partials/aren't routed as pages.https://github-samples.github.io/agents-in-sdlc/(base path/agents-in-sdlc).3. Multi-path lesson structure
Workshop content is now organized by tool path so learners can follow the agent surface they care about:
cli/— Copilot CLI lessonsvscode/— VS Code agent mode lessonscloud/— Cloud agent lessonsshared/— Lessons that apply to multiple paths (e.g.shared/cloud-agent/cloud-agent.mdx)Per-path "stub" pages redirect to shared lessons with a "Return to your path" footer so learners always get back to their track.
4. Partials system
Reusable MDX fragments under
_partials/with a strict naming convention:callout-*— short callouts (single<Aside>or short note)section-*— multi-paragraph reusable content (intros, recaps, overviews)exercise-*— self-contained hands-on steps that drop into a numbered listPartials are required to be self-contained (any link reference defined inside the partial). Established conventions documented in
.github/instructions/partials.instructions.md.Concrete dedup landed in this branch: MCP overview, model-choice caution, cloud-agent intro/security, instructions overview, iterating recap, accessibility scenario, tech-debt scenarios, copilot-CLI start callouts, docstring exercise, prereqs.
5. GitHub.com-readable Markdown mirror
scripts/render-markdown.pyrenders MDX into plain Markdown underworkshop/so learners can take the workshop directly on github.com without leaving the repo or running a build. The renderer:<Aside>components to GitHub admonitions (> [!NOTE]etc.).mdpaths6. CI
.github/workflows/pages.yml— builds the Astro site on PR (validation only) and deploys to GitHub Pages on push tomain. Lychee runs against the built HTML..github/workflows/render-markdown.yml— runs the renderer + lychee onworkshop/**/*.mdas a hard-fail gate on PRs. On push tomain, regeneratesworkshop/and bot-commits any diff back with[skip ci]. Path filters prevent recursive triggering.Authors do not need to run the renderer locally; the bot owns
workshop/.7. Author-facing docs and clean folder layout
AUTHORING.md— author entry point: mental model, file map, recipe-style step-by-steps for adding lessons / partials / images / edits, local preview, style essentials, CI expectations, troubleshooting.CONTRIBUTING.md— drops the Go template boilerplate; short pointer to AUTHORING.md plus PR/CI rules.docs/READMEs for the content-only repo.workshop-content/(which sat next toworkshop/) into Astro's standard collection locationdocs/src/content/docs/. This eliminates the name collision and removes theworkshop-content/node_modulessymlink hack — packages now resolve natively fromdocs/node_modules.astro.instructions.md(sidebar is manually maintained, not auto-generated)..gitignore(__pycache__/, common venvs, etc.).Verification
python scripts/render-markdown.pycd docs && npm run builddocs/dist/).../edit/main/docs/src/content/docs/cli/1-install-copilot-cli.mdx(no doubled segments)lychee 'workshop/**/*.md'lychee 'docs/dist/**/*.html'Notable risks / reviewer notes
client/,server/,data/tailspin-toys.db, or app workflows will need to update togithub-samples/tailspin-toys.workshop/is bot-owned post-merge. Don't hand-edit it; the renderer regenerates on every push tomain.docs/src/content.config.tskeeps a customglob()loader on purpose — Starlight's defaultdocsLoader()only excludes underscore-prefixed filenames, not directories, so partials would route as pages..../edit/main/docs/(Starlight appends the project-rootedentry.filePath) rather than.../edit/main/docs/src/content/docs/(which would double up).pages.ymldeletes the old "Link node_modules into workshop-content" step entirely — that step would have started failing post-move because the parent dir no longer exists.Commit highlights
chore: start workshop paths restructure→feat: restructure workshop-content into multi-path layoutMigrate workshop docs from MkDocs to Astro + StarlightMove 'Custom instructions' into each path group as module 1+ per-path module-1 hands-onCentralize Copilot session intros into Aside partials+Adopt prefixed naming for partialsCollapse cloud-agent lesson into shared modulechore: strip application code (now in github-samples/tailspin-toys)chore(copilot): refocus configuration on workshop content authoringchore(copilot): import skills and agents from github/awesome-copilotfeat(workshop): add MDX→Markdown renderer script+generate workshop/ folder for GitHub.com learnersci(workshop): generate workshop/ on main, validate on PRdocs: add AUTHORING.md, rewrite CONTRIBUTING.md, fix stale astro guidancerefactor: move workshop-content into docs/src/content/docs/chore: add Python entries to .gitignore