Skip to content

Instantly share code, notes, and snippets.

@TheFreeman193

TheFreeman193/Updatable Help on GitHub Pages.md

Last active April 1, 2022 21:09
Show Gist options
  • Save TheFreeman193/fde11aee6998ad4c40a314667c2a3005 to your computer and use it in GitHub Desktop.
Save TheFreeman193/fde11aee6998ad4c40a314667c2a3005 to your computer and use it in GitHub Desktop.
Download ZIP
Using GitHub Pages as a container for PowerShell Updatable Help
Raw
Updatable Help on GitHub Pages.md

Using GitHub pages as a container for PowerShell Updatable Help

Introduction

The PowerShell updatable help system is a useful, if not under-utilised, way to supply up-to-date support documentation for your module. While its implementation and ongoing support from Microsoft for native PowerShell modules is questionable (in my opinion) to begin with, it remains under-used and, in many cases, an unrecognised method of supplying updates to help documentation. This may be, in part, related to the complicated way in which PowerShell is instructed to look for updatable help, and the requirement for a container to be made available as a static website; it peruses this in order to select the correct cabinet files to download and extract.

Note: This gist is not a guide on how to use updatable help; this is covered relatively comprehensively over at Microsoft docs. It is also not a guide on using GitHub Pages, see GitHub's documentation for this. You can also refer to the PlatyPS documentation for creating help files with Markdown.

Getting Started

Before starting, it may be helpful to take a look at Updatable Help Authoring to familiarise yourself with the structure used for updatable help. It is also briefly outlined below.

We will assume, for this gist, that you have used PlatyPS to create help documentation and then again to generate external help cabinet files. It should also have produced a HelpInfo XML document (in the format <ModuleName>_<ModuleGUID>_HelpInfo.xml). We will use the NordVPN-Servers module as an active example for the purposes of this gist. This module uses per-method Markdown help files, which have been compiled into XML help for each UI culture supported. These directories (here and here) have then been wrapped, again using PlatyPS, as help cabinets.

The pathway used to access the updatable help is as follows:

  • HelpInfoURI property in the module manifest, which points to a container for;
  • *_HelpInfo.xml file, which indexes cabinet files for each UI culture and points to;
  • *_aa-bb_HelpContent.cab files, depending on target UI culture

Here, we will be storing the HelpInfo file in the same place as the help cabinets, though it is entirely possible to use two different internet locations for these. This just means the URI's referenced in the module manifest and HelpInfo file, are the same.

HelpInfo XML

In this example, we have two sets of help documentation, one in the en-GB UI culture, and the other for en-US. We should therefore have two cabinet files, in the format <ModuleName>_<ModuleGUID>_<UICulture>_HelpContent.cab, plus a HelpInfo XML document:

  • NordVPN-Servers_49e3429a-230b-4bc4-81bf-eaa6f0bd2927_en-GB_HelpContent.cab
  • NordVPN-Servers_49e3429a-230b-4bc4-81bf-eaa6f0bd2927_en-US_HelpContent.cab
  • NordVPN-Servers_49e3429a-230b-4bc4-81bf-eaa6f0bd2927_HelpInfo.xml

The contents of the HelpInfo file will look something like this:

<?xml version="1.0" encoding="utf-8"?>
<HelpInfo xmlns="http://schemas.microsoft.com/powershell/help/2010/05">
  <HelpContentURI>https://thefreeman193.github.io/NordVPN-Servers/UpdatableHelp/</HelpContentURI>
  <SupportedUICultures>
    <UICulture>
      <UICultureName>en-US</UICultureName>
      <UICultureVersion>2.0.0.1</UICultureVersion>
    </UICulture>
    <UICulture>
      <UICultureName>en-GB</UICultureName>
      <UICultureVersion>2.0.0.1</UICultureVersion>
    </UICulture>
  </SupportedUICultures>
</HelpInfo>

Notable are the two UICulture sections for each version of our help documentation, and the HelpContentUI tag. The former are used by PowerShell to determine which cabinet files to look for. Since the HelpInfo and cabinet files will be in the same place, the HelpContentURI above is the same one we use in the module manifest:

# HelpInfo URI of this module
HelpInfoURI = 'https://thefreeman193.github.io/NordVPN-Servers/UpdatableHelp/'

Directory Structure on GitHub Pages

We now have all the files we need to supply the updatable help system. Here, we are using a subdirectory of the same GitHub pages repository as the module homepage and online documentation, but it is possible to use a separate repository for this, too. In the UpdatableHelp subdirectory, we have the 2 help cabinet files, and 1 xml file, as discussed above. The folder structure will look like this:

├───UpdatableHelp
│       NordVPN-Servers_49e3429a-230b-4bc4-81bf-eaa6f0bd2927_en-GB_HelpContent.cab
│       NordVPN-Servers_49e3429a-230b-4bc4-81bf-eaa6f0bd2927_en-US_HelpContent.cab
│       NordVPN-Servers_49e3429a-230b-4bc4-81bf-eaa6f0bd2927_HelpInfo.xml

Trying it Out

If everything is configured correctly, we should be able to update the help from within PowerShell:

Update-Help -Module NordVPN-Servers -Force -Verbose

VERBOSE: Your connection has been redirected to the following URI: "https://thefreeman193.github.io/NordVPN-Servers/UpdatableHelp/"
VERBOSE: Performing the operation "Update-Help" on target "NordVPN-Servers, Current Version: 2.0.0.1, Available Version: 2.0.0.1, UICulture: en-GB".
VERBOSE: NordVPN-Servers: Updated C:\NordVPN-Servers\en-GB\about_NordVPN-Servers_Classes.help.txt. Culture en-GB Version 2.0.0.1
VERBOSE: NordVPN-Servers: Updated C:\NordVPN-Servers\en-GB\about_NordVPN-Servers_Settings.help.txt. Culture en-GB Version 2.0.0.1
VERBOSE: NordVPN-Servers: Updated C:\NordVPN-Servers\en-GB\NordVPN-Servers-help.xml. Culture en-GB Version 2.0.0.1

Or, for a UI culture that is not the current default:

Update-Help -Module NordVPN-Servers -UICulture en-US -Force -Verbose

VERBOSE: Your connection has been redirected to the following URI: "https://thefreeman193.github.io/NordVPN-Servers/UpdatableHelp/"
VERBOSE: Performing the operation "Update-Help" on target "NordVPN-Servers, Current Version: 2.0.0.1, Available Version: 2.0.0.1, UICulture: en-US".
VERBOSE: NordVPN-Servers: Updated C:\NordVPN-Servers\en-US\about_NordVPN-Servers_Classes.help.txt. Culture en-US Version 2.0.0.1
VERBOSE: NordVPN-Servers: Updated C:\NordVPN-Servers\en-US\about_NordVPN-Servers_Settings.help.txt. Culture en-US Version 2.0.0.1
VERBOSE: NordVPN-Servers: Updated C:\NordVPN-Servers\en-US\NordVPN-Servers-help.xml. Culture en-US Version 2.0.0.1

As seen above, we can now provide new versions of the help documents without needing to release a new version of the module. To release an update, we simply generate new cabinet files from our modified documentation using PlatyPS, with a higher version number in the HelpInfo XML file, and upload these to our GitHub Pages repository.

Wrapping Things Up

The updatable help system takes a little setting up and can definitely be finicky to get working but, once operational, makes it a breeze to push changes to the help documentation for your module. With the availability of GitHub pages, it becomes trivial to host an updatable help container at no extra cost.

Having done this for my modules, I decided to poke around on GitHub to see if anyone else had figured this out. To my surprise, I couldn't find a single repo that was using GitHub Pages for updatable help. Furthermore, most users were not even using the HelpInfoURI property correctly, instead pointing it to the root of their module repository. A couple of modules were hosting updatable help containers on third-party websites, though these appeared to be demo or educational modules.

I personally reckon the updatable help system could use a proper overhaul, but as things stand, GitHub pages offers an intriguing solution for deploying compliant help containers.

- TheFreeman193

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment