Skip to content

feat(docs): Docusaurus 3 workshop site with MS Learn design#14

Open
jakkaj wants to merge 12 commits intojsburckhardt:mainfrom
jakkaj:docs/docusaurus-site
Open

feat(docs): Docusaurus 3 workshop site with MS Learn design#14
jakkaj wants to merge 12 commits intojsburckhardt:mainfrom
jakkaj:docs/docusaurus-site

Conversation

@jakkaj
Copy link
Copy Markdown

@jakkaj jakkaj commented Feb 24, 2026 •
edited
Loading

Docusaurus Workshop Site

A complete Docusaurus 3.9.2 documentation site for the 13-module Copilot CLI workshop, with Microsoft Learn visual design.

What's included

  • 17 content pages across 5 sections (Getting Started, Customization, Extensibility, Advanced, Reference)
  • MS Learn design system: Segoe UI fonts, three-blue palette, dark mode
  • Clean homepage with hero banner and Start Workshop CTA
  • Custom React components: IconCard, BoxCard, CardGrid, SVG icons
  • GitHub Actions deploy workflow (SHA-pinned, deploys to GitHub Pages)
  • Copilot instructions file for future content quality

Module mapping

Section Modules Pages
Getting Started 01-03 4 (Module 02 split into learning + reference)
Customization 04-06 3
Extensibility 07-09 3
Advanced 10-12 5 (Module 12 split into 3)
Reference - 1

⚠️ GitHub Pages Setup (required before first deploy)

After merging this PR, the repo owner needs to do these one-time steps to enable the site:

Step 1: Enable GitHub Pages with Actions source

  1. Go to Settings → Pages
  2. Under Build and deployment → Source, select GitHub Actions (not "Deploy from a branch")
  3. Click Save

Step 2: Allow the deployment environment

Enabling Pages in Step 1 automatically creates a github-pages environment. You may need to configure it:

  1. Go to Settings → Environments
  2. Click github-pages
  3. Under Deployment branches and tags, ensure main is allowed (default is "All branches" which is fine)
  4. If it's set to "Selected branches", click Add deployment branch rule and add main

Step 3: Merge and verify

  1. Merge this PR to main
  2. The Deploy Documentation Site workflow triggers automatically (it watches docs/docusaurus/**)
  3. Check progress at Actions tab
  4. Once complete, the site is live at: https://jsburckhardt.github.io/101-copilot-cli-sdd/

Note: The first deploy may take 1-2 minutes. Subsequent deploys only trigger when files under docs/docusaurus/ change on main.

Workflow details

The deploy workflow (.github/workflows/deploy-docs.yml):

  • Triggers on push to main when docs/docusaurus/** changes
  • Uses SHA-pinned GitHub Actions (checkout, setup-node, configure-pages, upload-pages-artifact, deploy-pages)
  • Builds with Node 20, npm ci, npm run build
  • Deploys the docs/docusaurus/build directory to GitHub Pages
  • Can also be triggered manually from the Actions tab (workflow_dispatch)

jakkaj and others added 12 commits February 24, 2026 11:41
@jakkaj
feat(docs): scaffold Docusaurus 3.9.2 site at docs/docusaurus/
a13444a 
Add Docusaurus project skeleton with:
- package.json with Docusaurus 3.9.2, React 19, Mermaid theme
- docusaurus.config.js with jakkaj org, dual mermaid config, minimal navbar/footer
- Auto-generated sidebar via sidebars.js
- Placeholder intro.md with valid frontmatter
- CSS placeholder for Phase 2 design system
- .gitignore entries for Docusaurus build artifacts

Build verified: npm run build passes with zero errors.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): add MS Learn design system, components, and hub homepage
20280bc 
Phase 2 of Docusaurus site: complete visual design system with
Microsoft Learn styling, custom React components, and hub landing page.

Components: HeroSection, IconCard, BoxCard, CardGrid, 4 SVG icons
CSS: Full MS Learn color system with dark mode (DYK-11 sidebar fix)
Homepage: Hero banner + 4 icon cards + 4 box card modules
Static: favicon.ico, .nojekyll, 4 box card SVG icons

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): add prominent Start Workshop CTA to hero section
39d144c 
Enlarged hero (48px padding, 48px title, 18px subtitle) with a
white call-to-action button linking to /docs/intro for the guided
workshop experience.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): add content structure, category pages, and migrated intro
a3b9adb 
Phase 3 of Docusaurus site: 5 category directories with generated-index
landing pages, migrated intro from Module 00 with Docusaurus conventions,
and placeholder pages for sidebar generation.

Sections: Getting Started, Customization, Extensibility, Advanced, Reference
Resolves the 4 category broken link warnings from Phase 2.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): add Microsoft logo to navbar
3df3172 
Copies microsoft-logo.svg from reference repo and adds logo config
to navbar (26x26, with border-right separator per MS Learn style).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): migrate Getting Started content (Modules 01-03)
dffb858 
Phase 4: Content migration for Getting Started section.
- installation.md from Module 01 (305 lines)
- modes-and-commands.md split from Module 02 (concepts + 9 exercises)
- command-reference.md split from Module 02 (tables + reference)
- session-management.md from Module 03 (395 lines)

All Docusaurus conventions applied: admonitions, * lists, frontmatter,
language-tagged code blocks, no em dashes, MDX-safe URLs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): migrate Customization content (Modules 04-06)
78a6493 
Phase 5: Content migration for Customization section.
- custom-instructions.md from Module 04 (534 lines, Zone B with details)
- tools-and-permissions.md from Module 05 (455 lines)
- mcp-servers.md from Module 06 (490 lines)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): migrate Extensibility content (Modules 07-09)
5b41a5e 
Phase 6: Content migration for Extensibility section.
- agent-skills.md from Module 07 (648 lines, Zone B with details)
- plugins.md from Module 08 (493 lines)
- custom-agents.md from Module 09 (667 lines, Zone B with details)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): migrate Advanced content (Modules 10-12, with triple split)
4d1f31f 
Phase 7: Content migration for Advanced section.
- hooks.md from Module 10 (589 lines)
- context-management.md from Module 11 (480 lines)
- advanced-topics.md from Module 12 split 1/3 (326 lines)
- automation-patterns.md from Module 12 split 2/3 (469 lines)
- team-patterns.md from Module 12 split 3/3 (358 lines, with celebration)

Module 12 (1125 lines, 18min) split into 3 pages per sizing rules.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): add CI/CD workflow, instructions, and full navigation
b1434fb 
Phase 8: Final production readiness.
- .github/workflows/deploy-docs.yml (SHA-pinned, Node 20, GitHub Pages)
- .github/instructions/docusaurus-edits.instructions.md (applyTo docs/docusaurus/**)
- Navbar: Sections dropdown with 4 category links
- Footer: 3 columns with all section links
- onBrokenLinks upgraded from 'warn' to 'throw' (all 17 pages exist)
- Deprecated onBrokenMarkdownLinks key removed
- Build passes with ZERO errors and ZERO broken links

GitHub Pages setup (manual, one-time):
1. Go to repo Settings → Pages
2. Source: select 'GitHub Actions'
3. Go to Settings → Environments → github-pages
4. Under Deployment branches, add 'main' (or allow all branches)
5. Merge this branch to main to trigger the first deploy
6. Site will be live at https://jakkaj.github.io/101-copilot-cli-sdd/

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
ci: add docs/docusaurus-site branch to deploy trigger
0cbade3 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jakkaj
feat(docs): simplify homepage to clean hero with Start Workshop button
0df1982 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jakkaj