🩹 [Patch]: Add Linter settings + fix documentation structure (#535)

## Description

This pull request primarily fixes the documentation of PowerShell
functions by adding PowerShell-formatted code blocks to the `.EXAMPLE`
sections, due to upgrading from `platyPS` to
`Microsoft.PowerShell.PlatyPS`. Additionally, it introduces
configuration changes for linters and minor formatting corrections.

Documentation improvements:

* Added PowerShell-formatted code blocks to the `.EXAMPLE` sections of
many function files in `src/functions/*`. This was needed to retain the
code blocks in the examples, as `Microsoft.PowerShell.PlatyPS` lets the
user configure this.

Linter and configuration updates:

* Added a `Linter` section to `.github/PSModule.yml` to explicitly
disable several validation checks, such as `VALIDATE_BIOME_FORMAT` and
`VALIDATE_POWERSHELL`.
* Fixed a minor formatting issue in `.github/linters/.markdown-lint.yml`
by changing double quotes to single quotes for the `MD026.punctuation`
setting. This was also due to `Microsoft.PowerShell.PlatyPS` adding H3
for types which can be same for `.INPUTS` and `.OUTPUTS`.

Encoding and formatting corrections:

* Added or corrected UTF-8 BOM in some PowerShell files to ensure proper
encoding.

Author: MariusStorhaug

.github/PSModule.yml

@@ -19,3 +19,14 @@ Test:
 # Build:
 #   Docs:
 #     Skip: true
+
+Linter:
+  env:
+    VALIDATE_BIOME_FORMAT: false
+    VALIDATE_BIOME_LINT: false
+    VALIDATE_GITHUB_ACTIONS_ZIZMOR: false
+    VALIDATE_JSCPD: false
+    VALIDATE_JSON_PRETTIER: false
+    VALIDATE_MARKDOWN_PRETTIER: false
+    VALIDATE_YAML_PRETTIER: false
+    VALIDATE_POWERSHELL: false

.github/linters/.markdown-lint.yml

@@ -8,19 +8,19 @@
 ###############
 # Rules by id #
 ###############
-MD004: false                  # Unordered list style
+MD004: false # Unordered list style
 MD007:
-  indent: 2                   # Unordered list indentation
+  indent: 2 # Unordered list indentation
 MD013:
-  line_length: 808            # Line length
-MD024: false                  # no-duplicate-heading, INPUTS and OUTPUTS _can_ be the same item
+  line_length: 808 # Line length
+MD024: false # no-duplicate-heading, INPUTS and OUTPUTS _can_ be the same item
 MD026:
-  punctuation: ".,;:!。，；:"  # List of not allowed
-MD029: false                  # Ordered list item prefix
-MD033: false                  # Allow inline HTML
-MD036: false                  # Emphasis used instead of a heading
+  punctuation: '.,;:!。，；:' # List of not allowed
+MD029: false # Ordered list item prefix
+MD033: false # Allow inline HTML
+MD036: false # Emphasis used instead of a heading
 
 #################
 # Rules by tags #
 #################
-blank_lines: false  # Error on blank lines
+blank_lines: false # Error on blank lines

src/classes/public/GitHubPermission.ps1

@@ -1,4 +1,4 @@
-class GitHubPermission : System.IEquatable[Object] {
+class GitHubPermission : System.IEquatable[Object] {
     # The programmatic name of the permission as returned by the GitHub API
     [string] $Name
 

src/functions/private/Actions/Import-GitHubEventData.ps1

@@ -9,7 +9,9 @@ function Import-GitHubEventData {
         Import data from the event that triggered the workflow.
 
         .EXAMPLE
+        ```powershell
         Import-GitHubEventData
+        ```
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '',

src/functions/private/Actions/Import-GitHubRunnerData.ps1

@@ -7,7 +7,9 @@
         Import data about the runner that is running the workflow.
 
         .EXAMPLE
+        ```powershell
         Import-GitHubRunnerData
+        ```
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '',

src/functions/private/Actions/Workflow Run/Get-GitHubWorkflowRunByRepo.ps1

@@ -12,12 +12,16 @@
         `created`, `event`, `head_sha`, `status`.
 
         .EXAMPLE
+        ```powershell
         Get-GitHubWorkflowRunByRepo -Owner 'owner' -Repository 'repo'
+        ```
 
         Lists all workflow runs for a repository.
 
         .EXAMPLE
+        ```powershell
         Get-GitHubWorkflowRunByRepo -Owner 'owner' -Repository 'repo' -Actor 'octocat' -Branch 'main' -Event 'push' -Status 'success'
+        ```
 
         Lists all workflow runs for a repository with the specified actor, branch, event, and status.
 

src/functions/private/Actions/Workflow Run/Get-GitHubWorkflowRunByWorkflow.ps1

@@ -13,12 +13,16 @@
         `created`, `event`, `head_sha`, `status`.
 
         .EXAMPLE
+        ```powershell
         Get-GitHubWorkflowRunByWorkflow -Owner 'octocat' -Repository 'Hello-World' -ID '42'
+        ```
 
         Gets all workflow runs for the workflow with the ID `42` in the repository `Hello-World` owned by `octocat`.
 
         .EXAMPLE
+        ```powershell
         Get-GitHubWorkflowRunByWorkflow -Owner 'octocat' -Repository 'Hello-World' -ID '42' -Actor 'octocat' -Branch 'main' -Event 'push' -Status 'success'
+        ```
 
         Gets all workflow runs for the workflow with the ID `42` in the repository `Hello-World` owned by `octocat` that were triggered by the user
         `octocat` on the branch `main` and have the status `success`.

src/functions/private/Apps/GitHub Apps/Add-GitHubKeyVaultJWTSignature.ps1

@@ -8,7 +8,9 @@
         The function supports authentication via Azure CLI or Az PowerShell module and returns the signed JWT as a secure string.
 
         .EXAMPLE
+        ```powershell
         Add-GitHubKeyVaultJWTSignature -UnsignedJWT 'header.payload' -KeyVaultKeyReference 'https://myvault.vault.azure.net/keys/mykey'
+        ```
 
         Output:
         ```powershell

src/functions/private/Apps/GitHub Apps/Add-GitHubLocalJWTSignature.ps1

@@ -8,7 +8,9 @@
         This function handles the RSA signing process and returns the complete signed JWT.
 
         .EXAMPLE
+        ```powershell
         Add-GitHubLocalJWTSignature -UnsignedJWT 'eyJ0eXAiOi...' -PrivateKey '--- BEGIN RSA PRIVATE KEY --- ... --- END RSA PRIVATE KEY ---'
+        ```
 
         Adds a signature to the unsigned JWT using the provided private key.
 

src/functions/private/Apps/GitHub Apps/Get-GitHubAppAsAuthenticatedApp.ps1

@@ -13,7 +13,9 @@
         to access this endpoint.
 
         .EXAMPLE
+        ```powershell
         Get-GitHubAppAsAuthenticatedApp
+        ```
 
         Get the authenticated app.