For a long time I have wanted to do updatable help for the PoshSec PowerShell module. For some reason, I was never able to put two and two together to actually get updatable help implemented. This is my guide as to how I did it in preparation for the upcoming PoshSec 2.0 release.
What is updatable help?
Updatable help is a feature of PowerShell that lets you download updates to the help files associated with PowerShell. To update help on your own computer, you would run Update-Help at a PowerShell prompt that is running as administrator. This will then go fetch the newest version of help files from the internet.
How do we implement updatable help?
There are a few prerequisites to be able to use updatable help with your PowerShell module.
- A place to host your help files. I will be hosting PoshSec’s on the PoshSec web server.
- The platyPS module. This module is published by the Microsoft PowerShell team and allows you to create PowerShell help files using Markdown. You can grab the module by downloading it at https://github.com/PowerShell/platyPS or by running
Install-Module -name platyPS at an elevated PowerShell prompt.
- A module you can load using
Import-Module.
- Comment based help for your functions and commands.
Next you need to be in the directory you would want to store the help files. I am storing mine in the root of my Github directory in a folder named docs. See the picture below of my PoshSec folder structure on my desktop.
And inside of my docs folder I have three folders. They are named Cab, en-US and Markdown respectively.
These directories are important along each step of the updatable help journey. Lets begin by importing our module. Obviously, you would import the module you are doing the help for.
Import-Module -Name PoshSec
Once the module is imported, you are going to generate the Markdown help files. This is where the first directory comes into place. From my Github root directory, I run the following command:
New-MarkdownHelp -Module PoshSec -WithModulePage -OutputFolder .\Docs\Markdown
The module parameter and the output folder parameters are pretty self explanatory, but the -WithModulePage needs a little discussion. This Markdown file contains a list of descriptions of the commands or functions found within the module. This is the beggining of my PoshSec.md file created with the above command. I had to edit the descriptions of each command in the file.
Here is a look into what the PoshSec.md file is before I edited the file. The lines that the red arrows are the lines I edited. The first arrow is the link where you are going to store the help files. The PoshSec module help files are stored at https://www.poshsec.com/help/. Second, you edit the module help version number. Since PoshSec is working towards version 2.0, I filled in 1.0.0.0. You would update this with the version number you need for your project. The last two arrows are examples of things that I needed to edit to get this to work.
Here is a look at the completed PoshSec.md file that I have created for my updatable help files.
Once you are done editing, you are ready to move on to the next step.
The next step after editing the Markdown files, you are going to create the MAML (also known as Microsoft Assistance Markup Language) files. MAML files are what Updatable help uses to update the help files on your computer. You can edit MAML files directly, but using platyPS is much easier. The command below is what I used to create the MAML file for PoshSec. Again, I am running this command from the root directory of the PoshSec Module.
New-ExternalHelp .\Docs\Markdown -OutputPath .\Docs\en-US\
This command is pretty straight forward. If you are generating help in other languages, you can modify the output path to have that language qualifier. Like I said, this command is really simple and straight forward.
Now onto the final step. This last step before copying to your hosting provider is to create the actual CAB file that the Update-Help command actually downloads and installs. This command puts all the pieces together. The first parameter, -CabFilesFolder is the location of the CAB files you created in the last part. The -LandingPagePath parameter is the Markdown file you created above and edited with your module information. Finally, the -OutputFolder parameter is where you want to drop your CAB file.
New-ExternalHelpCab -CabFilesFolder .\Docs\en-US\ -LandingPagePath .\Docs\PoshSec.md -OutputFolder .\Docs\Cab\
Here is a view of my CAB folder. It is a little misleading as all three files are created, but no worries. You now have your files that you need for updatable help.
Next you are going to update your .PSD1 file to have the help file location. You are going to open your module file and search for the HelpInfoURI section. It should be commented out or you are going to have to create the line. This is what PoshSec’s looks like after I edited it.
Now it is time to copy your help files to a location you can use with Update-Help. Once you are done, you are going to want to re-import your module and then run Update-Help. Here are the commands that I used in order to validate my new help files worked.
Remove-Module -Name PoshSec
Import-Module -Name PoshSec
Update-Help -Module -Verbose -Force
Note: You can only run Update-Help once a day without the -Force Parameter.
This is what it looks like when I run Update-Help -Module PoshSec -Verbose -Force
Wrapup
Hopefully, with this post you have discovered that publishing updatable help is really easy with platyPS. This method has worked for me for PoshSec and hopefully it can help you with your module as well.
If you have any questions, please reach out to me on Twitter or email and Happy Scripting!
