Skip to content

copilot-instructions.md

Latest commit

 

History

History
175 lines (128 loc) · 4.74 KB

copilot-instructions.md

File metadata and controls

175 lines (128 loc) · 4.74 KB
Raw

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:
---
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
---
  1. Write the README with: description, prerequisites, setup instructions
  2. Update the parent category's ## Contents table to include the new sample
  3. 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:

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:

---
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":

---
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:

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:

{: .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

New
{: .label .label-green }

Deprecated
{: .label .label-red }

Liquid Escaping

Markdown containing {% (e.g. URL-encoded params) must be wrapped:

{% raw %}
```
https://example.com?q={%22key%22:%22value%22}
```
{% endraw %}

Building and Testing Locally

# 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

# 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