microsoft
diff --git a/‎.github/copilot-instructions.md‎
Lines changed: 175 additions & 0 deletions b/‎.github/copilot-instructions.md‎
Lines changed: 175 additions & 0 deletions
diff --git a/‎.github/workflows/pages.yml‎
Lines changed: 51 additions & 0 deletions b/‎.github/workflows/pages.yml‎
Lines changed: 51 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 5 additions & 0 deletions b/‎.gitignore‎
Lines changed: 5 additions & 0 deletions
@@ -0,0 +1,175 @@
+# CopilotStudioSamples — Contributor Instructions
+
+This repo uses **Just the Docs** (Jekyll theme) to generate a documentation site with sidebar navigation and full-text search.
+
+## Adding a New Sample
+
+1. Create a folder under the right category: `authoring/`, `extensibility/`, `ui/`, `contact-center/`, `sso/`, `testing/`, `guides/`, `infrastructure/`
+2. Add a `README.md` (exact casing) with YAML front matter:
+
+```yaml
+---
+title: My Sample           # Appears in sidebar nav
+parent: Embed              # Must match parent page's title exactly
+grand_parent: UI           # Required for level 3 (grandchild) pages
+nav_order: 8               # Numeric position among siblings
+---
+```
+
+3. Write the README with: description, prerequisites, setup instructions
+4. Update the parent category's `## Contents` table to include the new sample
+5. Test locally: `bundle install && bundle exec jekyll serve`
+
+### Hierarchy Levels
+
+| Level | Front matter | Example |
+|-------|-------------|---------|
+| Category | `title`, `nav_order`, `has_children: true`, `has_toc: false` | `ui/README.md` |
+| Subcategory | `title`, `parent`, `nav_order`, `has_children: true`, `has_toc: false` | `ui/embed/README.md` |
+| Sample | `title`, `parent`, `grand_parent`, `nav_order` | `ui/embed/servicenow-widget/README.md` |
+| Deep page | `nav_exclude: true`, `search_exclude: false` | Internal subfolders |
+
+### Power Platform Solutions (`authoring/solutions/`)
+
+Solutions follow the [PnP format](https://github.com/pnp/powerplatform-samples):
+
+```
+authoring/solutions/my-solution/
+├── README.md       # Description, screenshots, install steps
+├── assets/         # Screenshots and diagrams
+├── solution/       # Packaged .zip file(s) ready to import
+└── sourcecode/     # Unpacked source (pac solution unpack)
+```
+
+Front matter:
+```yaml
+---
+title: My Solution
+parent: Solutions
+grand_parent: Authoring
+nav_order: 7
+---
+```
+
+README should include: what it does, screenshots in `assets/`, import steps, connection references to configure, known issues. Update `authoring/solutions/README.md` Contents table after adding.
+
+### External Samples (code in another repo)
+
+Add `external_url` to front matter. This shows a "View sample in M365 Agents SDK repo" button instead of "Browse source on GitHub":
+
+```yaml
+---
+title: Genesys Handoff
+parent: Contact Center
+nav_order: 4
+external_url: "https://github.com/microsoft/Agents/tree/main/samples/dotnet/GenesysHandoff"
+---
+```
+
+### Deprecated Samples
+
+Add a red label and caution callout:
+
+```markdown
+Deprecated
+{: .label .label-red }
+
+{: .caution }
+> This sample is deprecated. Use [replacement](../path/) instead.
+```
+
+## Markdown Rules
+
+### Callouts — do NOT use GitHub `> [!NOTE]` syntax
+
+Jekyll doesn't support GitHub alerts. Use JTD kramdown callouts:
+
+```markdown
+{: .note }
+> This is a note.
+
+{: .warning }
+> A warning.
+
+{: .tip }
+> A tip.
+
+{: .caution }
+> A caution.
+
+{: .important }
+> Important info.
+```
+
+### Links Between Pages
+
+- README links: use directory path `[Sample](./my-sample/)` — NOT `(./my-sample/README.md)`
+- Other .md files: drop the extension `[Setup](./SETUP)` — NOT `(./SETUP.md)`
+- External URLs: use as-is
+
+### Labels
+
+```markdown
+New
+{: .label .label-green }
+
+Deprecated
+{: .label .label-red }
+```
+
+### Liquid Escaping
+
+Markdown containing `{%` (e.g. URL-encoded params) must be wrapped:
+
+````markdown
+{% raw %}
+```
+https://example.com?q={%22key%22:%22value%22}
+```
+{% endraw %}
+````
+
+## Building and Testing Locally
+
+```bash
+# Install dependencies (first time only)
+bundle install
+
+# Start dev server with live reload
+bundle exec jekyll serve
+# Site at http://127.0.0.1:4000/CopilotStudioSamples/
+
+# Build without serving (CI check)
+bundle exec jekyll build
+```
+
+Verify after changes:
+- New page appears in sidebar nav
+- Search finds the new sample (Ctrl+K)
+- Internal links work (no 404s)
+- Images render correctly
+
+## Git Workflow
+
+```bash
+# Work on the docs branch
+git checkout reorg/v1
+
+# Make changes, then commit
+git add -A
+git commit -m "Add my-new-sample to ui/embed"
+
+# Push to fork — GitHub Actions deploys automatically
+git push origin reorg/v1
+```
+
+- **Branch**: `reorg/v1` is the docs branch. GitHub Actions builds and deploys to Pages on every push.
+- **To merge upstream**: open a PR from `reorg/v1` → `main`. Update `.github/workflows/pages.yml` to trigger on `main` instead of `reorg/v1` before merging.
+- **Remotes**: `origin` = fork (`microsoft/CopilotStudioSamples`), `upstream` = source (`microsoft/CopilotStudioSamples`)
+
+## Config Gotchas
+
+- `_config.yml` exclude patterns match recursively (`*` matches `/` in Jekyll)
+- **Never add `*.html` to exclude** — it breaks theme layout files
+- File must be named `README.md` (exact casing) for `jekyll-readme-index` to work
+- Category READMEs use `has_toc: false` with a manual Contents table
@@ -0,0 +1,51 @@
+name: Deploy Jekyll site to Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
@@ -332,3 +332,8 @@ ASALocalRun/
 /sabacha/Dispatcher/dispatcher.bot
 SharePointSSOComponent/package-lock.json
 SharePointSSOComponent/config/serve.json
+
+# Jekyll
+_site/
+.jekyll-cache/
+.jekyll-metadata