Build Beautiful Documentation with platyPS and Material for MkDocs
summary
Workshop builds a real docs site from a PowerShell module using platyPS to emit Markdown and MAML, MkDocs + Material for MkDocs to render it, and GitHub Actions + Pages to publish. Commands demonstrated include new-markdownhelp and update-markdownhelp, plus local preview with mkdocs serve and deployment via mkdocs gh-deploy. Scaffolding uses stucco/devcontainers; the pipeline auto-builds and pushes HTML. Notes cover the progressAction parameter introduced in PowerShell 7.4 and when generated help needs manual cleanup.
AI-written summary · about
chapters (19)
- 0:00Building documentation
- 1:09Introduction
- 5:27Invest in documentation
- 15:10Workshop setup
- 21:55Tools overview
- 31:52GitHub Codespaces setup
- 33:17New MkDocs project
- 43:45Generate docs with platyPS
- 58:30Update docs with platyPS
- 1:00:43GitHub Actions deployment
- 1:10:34GitHub Pages hosting
- 1:29:22Q&A
- 1:33:39Deeper dive into tools
- 1:49:56Material theme customization
- 2:01:47Scaffolding module with stucco
- 2:13:56Module structure and dependencies
- 2:27:07Automate docs quality checks
- 2:39:45Adding online help links to documentation
- 2:42:59Versioning strategies
related talks
01h 01mClosing the documentation gap with Backstage.io
40mDevOpsDocs: Transforming Tediousness into Joy
44mSipping psake: Creating a Build and Release Pipeline for ...
46mAutomate Documentation with Sphinx & GitHub Actions
51mPowerShell module toolbox and templates for Continuous Delivery
25mBuilding Docs like Code: Continuous Integration for Documentation
45mGitHub Actions for Fun and Profit
23mTreating Documentation like Code: a Practical Account