How pnp/script-samples works
Project type and purpose
• This is a sample-script monorepo and documentation site for “PnP Script Samples.”
• It hosts 300+ PowerShell/CLI/Graph SDK script examples, generates static docs via DocFX, and deploys them (e.g., to GitHub Pages or another static-hosting endpoint).
File structure
Top-level:
• .devcontainer/ – VS Code dev container Dockerfile & scripts
• .github/workflows/ – CI/CD pipeline definitions
• docfx/ – DocFX config, templates, assets, scripts for static site generation
• scripts/ – Hundreds of sample subfolders; each contains PowerShell/JSON/assets and its own README
• README.md, LICENSE, .gitignore, .tours (onboarding tours), New-Sample.ps1
Key patterns:
• “scripts/…” – Each scenario is an independent component (PowerShell module + sample JSON + docs)
• “docfx/…” – Static site generator orchestrator (metadata, content, templates, build scripts)
• CI/CD via GitHub Actions: triggers docfx-generate and deploy workflows
• Devcontainer sets up local dev sandbox with Docker + VS Code for editing, testing DocFX builds
README for additional insights
• Purpose is to showcase real-world PnP/PowerShell/CLI samples
• Primary UX is the static website at https://pnp.github.io/script-samples
• Contributions process described; site supports filtering/navigation
a. Main components
1. Developer Local Environment
– VS Code + Devcontainer (Docker).
– Edits “scripts/” and “docfx/” content.
2. Version Control & CI/CD
– GitHub repo.
– Workflows (.github/workflows/docfx-generate.yml, takeaction.yml).
3. Static Site Generator
– DocFX engine (docfx.exe invoked by build.ps1).
– Uses docfx.json, templates, markdown includes, assets to produce docs.
4. Artifact Storage & Hosting
– Built static site files (HTML/CSS/JS) reside in docfx/_site or commit to gh-pages.
– Hosted on GitHub Pages or Azure Static Web Apps (via workflow).
5. End Users
– Browser requests static content; sees navigation, script details, samples.
b. Relationships & interactions
– Dev → Push to GitHub → triggers CI workflows
– CI: fetch repo → run DocFX build → produce static assets → deploy to hosting
– Browser ← HTTP GET ← Hosted site → static assets served
– Scripts folder feeds into DocFX pipeline as content modules
c. Architectural patterns & design principles
– Monorepo: all scripts + docs in one repo
– Static site generator pattern (content + templates → build → static output)
– CI/CD pipeline as code in GitHub Actions
– Devcontainer for reproducible local environment
d. Relevant technologies
– PowerShell scripts (samples)
– DocFX (static site generator)
– GitHub Actions
– Docker (devcontainer)
– Markdown, JSON assets, HTML/CSS templates
Elements
• Blue for developer/local
• Orange for CI/CD
• Green for static generator
• Gray for hosting
• Purple for user/client
• Rectangles for processes (DocFX build, Docker container)
• Clouds for hosting/web