Start PowerShell Demo from Markdown

by Doug Finke on July 1, 2013

in Markdown,Microsoft,PowerShell

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

I added a few lines of PowerShell to start-demo.ps1 so now I can author my demos in a tool like, Markdown Pad.

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.

image

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.

image

Notes

  • 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 “`.

Grab the PowerShell Script

Here on GitHub.

{ 0 comments… add one now }

Leave a Comment

You can use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

You are forbidden!