| name | windows-docs |
| description | Add OS-specific tabs to MkDocs documentation for Windows/PowerShell support. Use when: updating docs with Bash/PowerShell tabs, adding Windows instructions to workshop guides, converting documentation for cross-platform support, mkdocs content tabs for OS-specific commands. |
| argument-hint | Specify the doc file or camp docs folder, e.g., 'docs/camps/camp3-io-security/' |
Windows Documentation Tabs
Add === "Bash" / === "PowerShell" content tabs to MkDocs Material documentation so Windows users see PowerShell equivalents. Camp 2 docs (docs/camps/camp2-gateway/) are the completed reference — use them as the template.
When to Use
- After converting a camp's
.sh scripts to .ps1 (using the /windows-scripts skill)
- Adding cross-platform tabs to workshop documentation
- Updating doc files that reference shell scripts or shell-specific commands
Procedure
Step 1: Identify Docs to Update
Find all documentation files for the target camp:
docs/camps/<camp>/*.md
docs/camps/<camp>/**/*.md
Step 2: Find Script References
Search each doc file for bash code blocks that reference camp scripts or use shell-specific commands:
Must be tabbed (shell-specific):
./scripts/*.sh → needs ./scripts/*.ps1 tab
grep → needs Select-String tab
azd env get-values | grep ... → needs | Select-String ... tab
- Variable assignment with
$() subshells → needs PowerShell equivalent
cat, cut, sed, awk piped commands
- Entra ID app deletion with Bash variable capture
Do NOT tab (cross-platform, same syntax):
azd provision, azd up, azd down, azd deploy
azd env get-value SINGLE_VAR (no pipes)
az account show, az login
git clone, cd, docker commands
- JSON/YAML/XML code blocks
- Expected output blocks (just showing text)
Step 3: Apply Tabs
Wrap each shell-specific code block in content tabs. See the tab patterns reference for exact syntax at every indentation level.
Critical rules:
- Indentation matters — tabs inside admonitions (
???, !!!, ???+) need extra 4-space indent per nesting level
- Blank line required between
=== "Bash" and === "PowerShell" blocks
- Code block indent must be 4 spaces deeper than the
=== line
- No blank line between
=== line and its code fence
Step 4: Add Windows Tip
Add a tip callout on the camp's main index page (if not already present):
!!! tip "Windows Users"
All scripts in this camp have PowerShell equivalents (`.ps1`). When you see `./scripts/X.sh`, you can run `./scripts/X.ps1` instead.
Or for sections with a working directory tip:
!!! tip "Working Directory"
All commands in this section should be run from the `camps/<camp>` directory:
```bash
cd camps/<camp>
```
**Windows users:** Each `.sh` script has a `.ps1` equivalent. Use `./scripts/X.ps1` instead of `./scripts/X.sh`.
Step 5: Verify
- Check that all script references have tabs
- Check indentation alignment (especially inside admonitions)
- Confirm cross-platform commands (azd, az, git) are NOT tabbed
- Optionally, run
mkdocs serve to preview locally
Reference Implementation
See docs/camps/camp2-gateway/ for the complete reference:
Quick Reference
See the full tab patterns reference for before/after examples at every indentation level.