Update for Docusaurus v3 and PowerShell 4.7

.github/actions/bump-main/action.yml

@@ -10,7 +10,7 @@ runs:
   using: composite
   steps:
     - name: Checkout Main
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         path: __main
         ref: main

.github/actions/psgallery-publisher/action.yml

@@ -10,7 +10,7 @@ runs:
   using: composite
   steps:
     - name: Download Build Output
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
 
     - name: Publish to PSGallery
       shell: pwsh

.github/workflows/main.yml

@@ -16,8 +16,12 @@ jobs:
     name: Build Module
     runs-on: windows-latest
     steps:
+    - name: Show Powershell Version
+      shell: pwsh
+      run: $PSVersionTable.PSVersion
+
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
@@ -46,25 +50,26 @@ jobs:
         destination: ${{github.workspace}}/output
 
     - name: Upload artifact Modules
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
+      id: upload-artifact-modules
       with:
         name: Modules
         path: ${{github.workspace}}/output
 
     - name: Upload artifact PesterTests
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: PesterTests
         path: ${{github.workspace}}/Tests
 
     - name: Upload artifact RequiredModules
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: RequiredModules
         path: ${{github.workspace}}/Dev/RequiredModules.psd1
 
     - name: Upload artifact PSScriptAnalyzer
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: PSScriptAnalyzer
         path: ${{github.workspace}}/PSScriptAnalyzerSettings.psd1
@@ -75,8 +80,12 @@ jobs:
     runs-on: windows-latest
     needs: build
     steps:
+    - name: Show Powershell Version
+      shell: pwsh
+      run: $PSVersionTable.PSVersion
+
     - name: Checkout sources
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
@@ -110,9 +119,14 @@ jobs:
         - ubuntu-22.04
         - macos-11
         - macos-12
+        - macos-13
     steps:
+    - name: Show Powershell Version
+      shell: pwsh
+      run: $PSVersionTable.PSVersion
+
     - name: Download artifacts
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
 
     - name: Display structure of downloaded artifacts
       run: ls -R
@@ -130,7 +144,7 @@ jobs:
         additionalModulePaths: ${{github.workspace}}/Modules
 
     - name: Upload artifact PesterResults
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: matrix.os == 'windows-2022' # only execute on this OS
       with:
         name: PesterResults
@@ -152,8 +166,12 @@ jobs:
     if: ${{ github.ref == 'refs/heads/main' && contains(github.event.head_commit.message, '[release]')}}
 
     steps:
+    - name: Show Powershell Version
+      shell: pwsh
+      run: $PSVersionTable.PSVersion
+
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
@@ -169,7 +187,7 @@ jobs:
         useConfigFile: true
 
     - name: Download Artifacts
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
 
     - name: Publish to PSGallery
       uses: ./.github/actions/psgallery-publisher

Tests/Integration/Bootstrap.ps1

@@ -13,6 +13,8 @@
     Each test has a correlating folder in $env:Temp named after the
     test containing all output produced by the test (if any)
 #>
+#Requires -Version 7.4
+
 param(
     [Parameter(Mandatory = $True)][System.IO.FileInfo]$TestFolder
 )

Tests/Integration/HtmlEncodeLessThanBrackets/Expected.mdx

@@ -12,7 +12,7 @@ Dummy module to ensure proper html encoding of platyPS escaped opening '<' an
 ## SYNTAX
 
 ```powershell
-Test-HtmlEncodeLessThanBrackets [[-Dummy] <String>] [<CommonParameters>]
+Test-HtmlEncodeLessThanBrackets [[-Dummy] <String>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -66,6 +66,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ProgressAction
+
+\{\{ Fill ProgressAction Description \}\}
+
+```yaml
+Type: ActionPreference
+Parameter Sets: (All)
+Aliases: proga
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

Tests/Integration/UnescapeInlineCode/Expected.mdx

@@ -12,7 +12,7 @@ Dummy module to ensure proper unescaping of `<angle brackets>` inside inline cod
 ## SYNTAX
 
 ```powershell
-Test-UnescapeInlineCode [[-Dummy] <String>] [<CommonParameters>]
+Test-UnescapeInlineCode [[-Dummy] <String>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -74,6 +74,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ProgressAction
+
+\{\{ Fill ProgressAction Description \}\}
+
+```yaml
+Type: ActionPreference
+Parameter Sets: (All)
+Aliases: proga
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

Tests/Unit/Bootstrap.ps1

@@ -12,6 +12,8 @@
     test containing all output produced by the test (if any)
 
 #>
+#Requires -Version 7.4.1
+
 param(
     [Parameter(Mandatory = $True)][System.IO.FileInfo]$TestFolder
 )

website/docs/commands/New-DocusaurusHelp.mdx

@@ -25,7 +25,7 @@ Generates Get-Help documentation in Docusaurus compatible `.mdx` format.
 New-DocusaurusHelp [-Module] <String> [[-DocsFolder] <String>] [[-Sidebar] <String>] [[-Exclude] <Array>]
  [[-EditUrl] <String>] [[-MetaDescription] <String>] [[-MetaKeywords] <Array>] [[-PrependMarkdown] <String>]
  [[-AppendMarkdown] <String>] [-KeepHeader1] [-HideTitle] [-HideTableOfContents] [-NoPlaceHolderExamples]
- [-Monolithic] [-VendorAgnostic] [<CommonParameters>]
+ [-Monolithic] [-VendorAgnostic] [-ProgressAction <ActionPreference>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -352,6 +352,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ProgressAction
+
+\{\{ Fill ProgressAction Description \}\}
+
+```yaml
+Type: ActionPreference
+Parameter Sets: (All)
+Aliases: proga
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
@@ -383,4 +399,4 @@ $tempFolder = Get-Item (Join-Path -Path ([System.IO.Path]::GetTempPath()) -Child
 
 ## ADDITIONAL INFORMATION
 
-This page was auto-generated using the comment based help in Alt3.Docusaurus.Powershell 1.0.32.
+This page was auto-generated using the comment based help in Alt3.Docusaurus.Powershell 1.0.35.

website/docs/commands/docusaurus.sidebar.js

@@ -1,7 +1,7 @@
 /**
  * Import this file in your Docusaurus `sidebars.js` file.
  *
- * Auto-generated by Alt3.Docusaurus.Powershell 1.0.32.
+ * Auto-generated by Alt3.Docusaurus.Powershell 1.0.35.
  *
  * Copyright (c) 2019-present, ALT3 B.V.
  *

website/docs/faq/multi-line-examples.mdx

@@ -29,7 +29,7 @@ and where it ends.
 
 Code fencing ensures identical rendering across all PowerShell versions and looks similar to:
 
-```
+````
 .EXAMPLE
     ```ps
     $description = 'Code Fenced example with a description'
@@ -44,7 +44,7 @@ Code fencing ensures identical rendering across all PowerShell versions and look
 
     - is treated as markdown
     - could also contain fenced code blocks itself
-```
+````
 
 **Please note** that you may use any of the following commonly used opening fences:
 
@@ -54,8 +54,8 @@ Code fencing ensures identical rendering across all PowerShell versions and look
 - \`\`\`powershell
 
 > For a full list of usage examples see
-> [this test module](https://github.com/alt3/Docusaurus.Powershell/blob/main/Tests/Integration/CrossVersionCodeExamples.psm1)
-> and [the markdown](https://github.com/alt3/Docusaurus.Powershell/blob/main/Tests/Integration/CrossVersionCodeExamples.expected.mdx)
+> [this test module](https://github.com/alt3/Docusaurus.Powershell/blob/main/Tests/Integration/CrossVersionCodeExamples/CrossVersionCodeExamples.psm1)
+> and [the markdown](https://github.com/alt3/Docusaurus.Powershell/blob/main/Tests/Integration/CrossVersionCodeExamples/Expected.mdx)
 > it renders.
 
 ## PowerShell 7 Native Multi-Lines

website/docs/installation.mdx

@@ -11,7 +11,17 @@ title: Installation
 
 ## Installation
 
+Open a PowerShell Core
+
+Install the required PowerShell modules once:
+
 ```powershell
 Install-Module Alt3.Docusaurus.Powershell -Scope CurrentUser
 Install-Module PlatyPS -Scope CurrentUser
 ```
+
+Install the Docusaurus website once:
+
+```powershell
+npx create-docusaurus@latest docusaurus classic
+```

website/docs/usage.mdx

@@ -3,39 +3,9 @@ id: usage
 title: Usage
 ---
 
-Adding Docusaurus to a PowerShell Module project requires three steps:
+Adding auto-generated Get-Help pages to to your Docusaurus website only requires two steps:
 
-1. Adding the Docusaurus website skeleton
-2. Generating Module documentation
-3. Starting the Website
-
-## Adding Docusaurus
-
-Open a PowerShell (Core).
-
-Cd into your project's root folder.
-
-Add the Docusaurus website skeleton by running:
-
-```powershell
-npx @docusaurus/init@next init docusaurus classic
-```
-
-Modify newly created file `docusaurus/sidebars.js` so it looks like this:
-
-```js
-const commands = require('./docs/commands/docusaurus.sidebar.js');
-
-module.exports = {
-  docs: {
-    Docusaurus: ['doc1', 'doc2', 'doc3'],
-    Features: ['mdx'],
-    "Command Reference": commands
-  },
-};
-```
-
-## Generating Module Documentation
+## Generate PowerShell Module Documentation
 
 To generate Get-Help pages for any PowerShell module run the following command.
 
@@ -48,10 +18,40 @@ New-DocusaurusHelp -Module "YourModuleName"
 After the command has completed, the `docusaurus/docs/commands` folder
 should contain one `.mdx` file for each command exported by the PowerShell module.
 
-## Starting the Website
+## Start the Website
 
 To start your website, cd into the `docusaurus` folder and run:
 
 ```powershell
-yarn start
+npm start
 ```
+
+## Sidebar layout
+
+By default, Docusaurus will automatically generate a sidebar from the docs folder structure.
+
+If you want to change the layout of the sidebar, update `docusaurus/sidebar.js` so it looks like this:
+
+```js
+const commands = require('./docs/commands/docusaurus.sidebar.js');
+
+// @ts-check
+
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+  tutorialSidebar: [
+    'intro',
+    {
+        type: 'category',
+        label: 'Command Reference',
+        items: [
+            commands
+        ],
+      },
+  ],
+};
+
+export default sidebars;
+```
+
+For more information about configuring the sidebar please visit https://docusaurus.io/docs/sidebar.