feat(docs): add Docusaurus 3 documentation site with GitHub Pages deployment

[jakkaj]

Description

This PR adds a Docusaurus 3 documentation site at docs/docusaurus/ with GitHub Pages deployment. The site provides a learning path structure for introducing HVE-Core — curated, sequential content sections that guide readers through the framework in a deliberate order.

This PR is the groundwork for the documentation site, not a proposal on exact content. Pages contain placeholder text that demonstrates the structure and conventions. Real content follows in subsequent PRs built on this foundation.

Related Issue(s)

Relates to #663

Type of Change

Code & Documentation:

• New feature (non-breaking change adding functionality)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow

AI Artifacts:

• Copilot instructions (.github/instructions/*.instructions.md)

Sample Prompts (for AI Artifact Contributions)

The docusaurus-edits.instructions.md file is an auto-applied instructions file, not an invocable agent or prompt. It activates automatically when editing any file matching docs/docusaurus/**.

User Request:
Open any .md file under docs/docusaurus/ and ask Copilot to help write or edit content.

Execution Flow:

1. User opens docs/docusaurus/docs/getting-started/overview.md
2. Copilot automatically loads docusaurus-edits.instructions.md via the applyTo: 'docs/docusaurus/**' pattern
3. All suggestions follow the conventions (frontmatter fields, admonition syntax, link formatting, tone)

Output Artifacts:
Markdown files under docs/docusaurus/docs/ that follow site conventions without the contributor explicitly reading them.

Success Indicators:

• Generated content uses :::note syntax instead of > [!NOTE]
• Internal links use relative paths without .md extension
• Frontmatter includes title, description, and sidebar_position

Testing

Manual verification:

• npm run build in docs/docusaurus/ completes with zero errors
• Dev server (npm start) renders all pages with working navigation
• Mermaid diagrams render on intro page and RPI workflow page
• Sidebar displays 6 sections with correct ordering
• Light and dark mode both render correctly

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

Required Automated Checks

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

All GitHub Actions in deploy-docs.yml are SHA-pinned per repository conventions. The workflow uses permissions: contents: read at job level and only grants pages: write and id-token: write at the workflow level for deployment.

---

Learning Path Architecture

The site is organized as a learning path rather than a flat reference wiki or a single linear tutorial. Each section is a self-contained sequence that readers can enter independently from the hub landing page, but within a section the pages follow a guided order with automatic "← Previous" / "Next →" navigation.

┌──────────────────────────────────────────────────────────┐
│  Landing Page (Hub)                                      │
│  Icon card grid → pick your starting point               │
└────────┬────────────┬──────────────┬─────────────────────┘
         ▼            ▼              ▼
  ┌───────────┐ ┌───────────┐ ┌───────────┐
  │ Getting   │ │ Workflows │ │ Agents &  │  ...3 more
  │ Started   │ │           │ │ Prompts   │  sections
  │           │ │           │ │           │
  │ 1.Overview│ │ 1.Overview│ │ 1.Overview│
  │ 2.Install │ │ 2.RPI     │ │ (future)  │
  │  (next →) │ │  (next →) │ │           │
  └───────────┘ └───────────┘ └───────────┘

Current Sections

#	Section	Pages	Purpose
—	Introduction	1	What is HVE-Core, value delivery loop (Mermaid diagram)
1	Getting Started	2	Setup, prerequisites, installation
2	Workflows	2	RPI workflow, development patterns
3	Agents & Prompts	1	Custom AI assistants (placeholder)
4	Instructions & Skills	1	Auto-applied conventions (placeholder)
5	Design Thinking	1	Planning workflow (placeholder)
6	Templates & Examples	1	Reusable patterns (placeholder)

Sections 1-2 have sequential depth. Sections 3-6 are single-page structural placeholders ready for content in follow-up PRs.

Microsoft Learn Visual Language

The site follows Microsoft Learn's design patterns adapted for Docusaurus, using the Fluent Design system.

Element	Implementation
Hero banner	Gradient header with title + subtitle, no image
Icon card grid	6 category cards with custom SVG icons on the hub page
Deep-dive cards	4 box cards with grouped link lists
Color palette	#0078D4 primary (Microsoft Blue), #4DA3E5 for dark mode
Typography	Segoe UI font stack with hierarchical sizing
Microsoft logo	Four-square SVG in the navbar
Theme overrides	Simplified breadcrumbs, footer, and collapsible TOC

No Microsoft Docusaurus theme package exists — the visual language is implemented through custom CSS (src/css/custom.css) and React components (src/components/).

What's Included

• Docusaurus 3 scaffold with Mermaid diagram support and Fluent Design CSS
• 6 content sections organized as a learning path with sequential navigation
• Landing page styled after Microsoft Learn with icon card grid and deep-dive cards
• GitHub Actions deploy workflow (deploy-docs.yml) with SHA-pinned actions, path-filtered triggers on push to main, and least-privilege permissions
• Copilot authoring conventions (docusaurus-edits.instructions.md) — auto-applied when editing any file under docs/docusaurus/, covering frontmatter, admonitions, linking, page structure, and tone guidelines
• justfile recipes for local development (docs-dev, docs-build, docs-serve)
• .gitignore patterns for build artifacts

What's NOT Included (By Design)

• Final documentation content — pages are structural placeholders
• Blog, versioned docs, i18n, or search integration
• Plan files, research artifacts, or workshop documents

Copilot Authoring Conventions

The docusaurus-edits.instructions.md file establishes authoring conventions that Copilot follows automatically when contributors edit documentation pages. Future content PRs get consistent quality without contributors needing to read a style guide.

Area	What It Covers
Frontmatter	Required fields (title, description, sidebar_position), optional fields
Admonitions	Docusaurus triple-colon syntax (not GitHub > [!NOTE] alerts)
Internal links	Relative paths without .md extension
Mermaid diagrams	Fenced code blocks with mermaid language identifier
Page structure	5-10 minute read time target, progressive disclosure with <details>
Tone	Lead with "why", address reader as "you", ground in concrete examples
Cross-linking	Link when unfamiliar, avoid over-linking
Value tags	🟢 Core / 🟡 Supporting / ⚪ Meta for artifact mentions

This file is an investment in future content quality — it's infrastructure for AI-assisted authoring, not just a style guide.

Site Structure

docs/docusaurus/
├── docs/
│   ├── intro.md                          # What is HVE-Core + value loop diagram
│   ├── getting-started/                  # Setup and first steps
│   │   ├── overview.md
│   │   └── installation.md
│   ├── workflows/                        # Core development patterns
│   │   ├── overview.md
│   │   └── rpi-workflow.md
│   ├── agents-and-prompts/               # Custom AI assistants (placeholder)
│   │   └── overview.md
│   ├── instructions-and-skills/          # Auto-applied conventions (placeholder)
│   │   └── overview.md
│   ├── design-thinking/                  # Planning workflow (placeholder)
│   │   └── overview.md
│   └── templates-and-examples/           # Reusable patterns (placeholder)
│       └── overview.md
├── src/
│   ├── components/                       # HeroSection, Cards (Learn-style)
│   ├── css/custom.css                    # Fluent Design palette
│   ├── data/hubCards.tsx                  # Landing page card definitions
│   ├── pages/index.tsx                   # Hub landing page
│   └── theme/                            # Breadcrumb, footer, TOC overrides
├── static/img/                           # Microsoft logo, icons
├── docusaurus.config.js
├── sidebars.js
└── package.json

.github/
├── instructions/
│   └── docusaurus-edits.instructions.md  # Copilot authoring conventions
└── workflows/
    └── deploy-docs.yml                   # GitHub Pages deployment

justfile                                  # docs-dev, docs-build, docs-serve

Setup Required

To enable deployment, a repo admin needs to:

1. Go to Settings → Pages → Source and select GitHub Actions
2. Ensure the target branch is allowed in Settings → Environments → github-pages → Deployment branches

The workflow builds correctly regardless of Pages configuration — the deploy step fails gracefully if Pages is not enabled.

Screenshots

Ours (left) vs Azure Architecture Center (right)

Additional Notes

Local Development

cd docs/docusaurus
npm install
npm start        # Dev server at localhost:3000/hve-core/
npm run build    # Production build

Or using the justfile (requires just):

just docs-dev    # Dev server
just docs-build  # Production build
just docs-serve  # Serve built site

[jakkaj]

P.S. You can review the site here: https://jakkaj.github.io/hve-core/.

Also you can set the gh pages to build on the branch ->

To test the documentation site from a PR branch before merging, two GitHub
settings need to be configured. First, go to Settings → Pages → Build and
deployment → Source and select GitHub Actions (not "Deploy from a branch").
This tells GitHub to use the workflow file rather than looking for a built
branch like gh-pages. Second, go to Settings → Environments → github-pages →
Deployment branches and tags, click Add deployment branch or tag rule, and add
the PR branch name (e.g. docs/docusaurus-site). By default, the github-pages
environment only allows deployments from the default branch — without this
step the build job succeeds but the deploy job fails silently with a branch
protection error. Once both settings are in place, any push to the allowed
branch that matches the workflow's path filter will build and deploy the site.
Remember to remove the extra branch from the environment rules and the
workflow triggers before merging to main.

he workflow's on.push.branches array also needs to include the PR
branch. Our workflow currently only has main, so to test from the branch you'd
temporarily add it:

on:
push:
branches:
- main
- docs/docusaurus-site # temporary — remove before merging

[vaughanknight]

Should add - the documentation is not real documentation, that we can get to. This was more thinking on how we could structure it for discovery, create a space for exploration of the content that's ultimately in the repo, and help identify gaps in the learning to drive adoption.

[WilliamBerryiii]

Should add - the documentation is not real documentation, that we can get to. This was more thinking on how we could structure it for discovery, create a space for exploration of the content that's ultimately in the repo, and help identify gaps in the learning to drive adoption.

That's ok ... there's a large batch of documentation inbound (#663) that will let me build off the base of this branch and get the site up and running.

@jakkaj - if it's cool, I'm gonna take the branch and run with it.

[WilliamBerryiii]

Summary of Changes

This PR introduces a full Docusaurus 3 documentation site with Microsoft Learn-inspired styling, GitHub Pages deployment, CI integration, and component testing. Here's a breakdown of everything included:

---

Docusaurus Site (docs/docusaurus/)

Scaffold & Configuration

• Docusaurus 3.9.2 site with React 19 and TypeScript
• docusaurus.config.js — site metadata, theme colors, navbar, footer, Mermaid support, GitHub Pages base URL
• sidebars.js — auto-generated sidebar from docs/ filesystem structure
• Custom CSS (src/css/custom.css) — Microsoft Learn color tokens, responsive layout, dark/light theme support

Custom Components

• BoxCard / IconCard / CardGrid — reusable card components with hover effects and icon support
• HeroSection — landing page hero with gradient background
• Icons — inline SVG icon components (Rocket, Book, Puzzle, etc.)
• Hub cards data file (src/data/hubCards.tsx) — card content for the landing page

Theme Overrides

• DocBreadcrumbs, Footer, TOCCollapsible — swizzled wrappers for Microsoft Learn styling

Static Assets

• Favicon, logo SVG, Microsoft logo, social card image
• Custom SVG icons for quickstart, customize, plan/architect, build-ai
• .nojekyll for GitHub Pages compatibility

Landing Page

• src/pages/index.tsx — hub-style landing page with hero + card grid

---

Documentation Content Updates (135 files changed)

Docusaurus Compatibility

• Added _category_.json files for sidebar ordering across all doc categories: getting-started, hve-guide, lifecycle, roles, rpi, architecture, contributing, security, templates, agents
• Fixed frontmatter and internal links for Docusaurus compatibility (removed .md extensions, adjusted relative paths)
• Added placeholder stub files for pages referenced in sidebars

Content Improvements

• docs/templates/brd-template.md — significant restructuring (+117 lines)
• docs/hve-guide/roles/tpm.md — expanded content (+27 lines)
• Various minor formatting and link fixes across existing docs

---

CI/CD & Workflows

New Workflows

• deploy-docs.yml — GitHub Pages deployment workflow (build + deploy with proper permissions)
• docusaurus-tests.yml — reusable workflow for Docusaurus component tests (Node 20, npm ci, jest)

Existing Workflow Updates

• pr-validation.yml — added Docusaurus test job call
• main.yml — added Docusaurus test job call

---

Docusaurus Instructions

• .github/instructions/docusaurus-edits.instructions.md — conventions for creating/editing Docusaurus pages (frontmatter, admonitions, links, Mermaid, images, code blocks, progressive disclosure, cross-linking)

---

Testing (29 tests, 5 suites — all passing)

Jest Configuration

• jest.config.js — ts-jest with jsdom environment, CSS module mocking via identity-obj-proxy, SVG mocking, Docusaurus module path mapping

Mock Files

• @docusaurus/Link — renders anchor tags with proper props
• @docusaurus/useBaseUrl — identity passthrough
• @theme/Layout — renders children with layout wrapper

Test Suites

• CardGrid.test.tsx — rendering, child composition, CSS class application
• IconCard.test.tsx — link rendering, icon display, content projection
• BoxCard.test.tsx — link behavior, icon rendering, content display
• HeroSection.test.tsx — heading and subtitle rendering
• Icons.test.tsx — SVG rendering for all icon components

---

Other

• .gitignore — added Docusaurus build output exclusions
• justfile — added Docusaurus dev/build/test recipes
• Root package.json — added Docusaurus-related npm scripts

---

Stats: 135 files changed, +28,096 / −203 lines (bulk is package-lock.json)