I use start-demo.ps1 in all my PowerShell presentations. It works by passing in a file name that contains PowerShell code. In the file, you typically have a comment, or comments followed by a line of PowerShell code. When you’re demoing to and stepping through, the comment displays first followed by the PowerShell code, and pressing enter and executes the PowerShell.
This is super handy and saves your audience from having to watch you type and make mistakes.
I had the thought that I’d like to have a demo and also be able to use the snippets from the demo in documentation. After Looking at a demo.txt file, it looked similar to Markdown. Markdown is a text-to-HTML conversion tool.
It’s Executable Documentation
Below is an an example of a PowerShell demo.md file in Markdown Pad, on the left, and the HTML preview of the same file on the right. One way to create a PowerShell comment is using the #. In Markdown, if a line of text starts with one or more # characters, it is translated to a HTML heading tag.
Run the PowerShell Demo
Using Start-DemoFromMD.ps1, this same markdown file can now be executed. Now I have a demo ready file and I can generate HTML for documentation.
- I started with Joel Bennett’s updated Start-Demo.ps1 here on poshcode.org and added a few lines of PowerShell
- Currently it only supports fenced code blocks, that is, text wrapped in “`.