Additional minor updates to documentation (#1240)

* Minor updates to documentation

docs/about.md

@@ -1,4 +1,5 @@
 ---
+title: What is PSRule and why should I use it?
 author: BernieWhite
 ---
 

docs/analysis-output.md

@@ -59,7 +59,7 @@ The output format can be configuring by setting the `Output.Format` option to on
 
 === "Options file"
 
-    ```yaml hl_lines="2-3"
+    ```yaml title="ps-rule.yaml" hl_lines="2-3"
     output:
       format: 'Sarif'
       path: reports/ps-rule-results.sarif

docs/authoring/testing-infrastructure.md

@@ -1,4 +1,5 @@
 ---
+title: Testing Infrastructure as Code
 author: BernieWhite
 ---
 

docs/authoring/using-expressions.md

@@ -78,4 +78,4 @@ _n/a_           | NullOrEmpty
 _n/a_           | TypeOf
 WithinPath      | WithinPath
 
-[^1]: The `Equals`, `HasValue` and expression and `HasFieldValue` are similar.
+[^1]: The `Equals`, `HasValue` expressions and `HasFieldValue` are similar.

docs/creating-your-pipeline.md

@@ -83,7 +83,7 @@ To prevent a rule executing you can either:
 
     [:octicons-book-24: Docs][3]
 
-    ```yaml
+    ```yaml title="ps-rule.yaml"
     rule:
       exclude:
       # Ignore the following rules for all objects
@@ -97,7 +97,7 @@ To prevent a rule executing you can either:
 
     [:octicons-book-24: Docs][4]
 
-    ```yaml
+    ```yaml title="ps-rule.yaml"
     suppression:
       Azure.AKS.AuthorizedIPs:
       # Exclude the following externally managed AKS clusters

docs/expressions/functions.md

@@ -44,7 +44,7 @@ The conditions that are supported are:
 
 ## Examples
 
-```yaml
+```yaml title="YAML"
 ---
 # Synopsis: An expression function example.
 apiVersion: github.com/microsoft/PSRule/v1

docs/expressions/sub-selectors.md

@@ -186,7 +186,7 @@ In the example:
 
 Given the example, is important to understand what happens if:
 
-- The `resources` property doesn't exist.
+- The `resources` property doesn't exist. **OR**
 - The `resources` property doesn't contain any items that match the sub-selector condition.
 
 In either of these two cases, the sub-selector will return `false` and fail the rule.

docs/faq.md

@@ -1,4 +1,5 @@
 ---
+title: Frequently Asked Questions
 author: BernieWhite
 ---
 

docs/features.md

@@ -1,4 +1,5 @@
 ---
+title: Key features of PSRule
 author: BernieWhite
 ---
 

docs/install-instructions.md

@@ -1,4 +1,5 @@
 ---
+title: Instructions for installing PSRule
 author: BernieWhite
 ---
 
@@ -16,7 +17,7 @@ It is shipped as a PowerShell module which makes it easy to install and distribu
 
 [:octicons-workflow-24: GitHub Action][1]
 
-Install and use PSRule with GitHub Actions by referencing the `Microsoft/ps-rule` action.
+Install and use PSRule with GitHub Actions by referencing the `microsoft/ps-rule` action.
 
 ```yaml
 - name: Analyze Azure template files

docs/license-contributing.md

@@ -1,3 +1,8 @@
+---
+title: License and contributing to PSRule
+author: BernieWhite
+---
+
 # License and contributing
 
 PSRule is licensed with an [:octicons-law-24: MIT License][1], which means it's free to use and modify.

docs/support.md

@@ -1,7 +1,11 @@
+---
+title: Support for PSRule
+author: BernieWhite
+---
+
 # Support
 
 This project uses GitHub Issues to track bugs and feature requests.
-<!-- Before logging an issue please see our [troubleshooting guide]. -->
 
 Please search the existing issues before filing new issues to avoid duplicates.
 
@@ -14,4 +18,3 @@ Support for this project/ product is limited to the resources listed above.
 
 [issue]: https://github.com/microsoft/PSRule/issues
 [discussion]: https://github.com/microsoft/PSRule/discussions
-<!-- [troubleshooting guide]: troubleshooting.md -->

docs/upgrade-notes.md

@@ -1,3 +1,8 @@
+---
+title: Notes for upgrading between PSRule versions
+author: BernieWhite
+---
+
 # Upgrade notes
 
 This document contains notes to help upgrade from previous versions of PSRule.

docs/validating-locally.md

@@ -5,28 +5,33 @@ author: BernieWhite
 # Validating locally
 
 PSRule can be installed locally on MacOS, Linux, and Windows for local validation.
+This allows you to test Infrastructure as Code (IaC) artifacts before pushing changes to a repository.
 
 !!! Tip
     If you haven't already, follow the instructions on [installing locally][1] before continuing.
 
-  [1]: install-instructions.md#installinglocally
+  [1]: install-instructions.md#installing-locally
 
 ## With Visual Studio Code
 
 [:octicons-download-24: Extension][2]
 
 An extension for Visual Studio Code is available for an integrated experience using PSRule.
-The Visual Studio Code extension includes a built-in `PSRule: Run analysis` task.
+The Visual Studio Code extension includes a built-in task _PSRule: Run analysis_ task.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/microsoft/PSRule-vscode/main/docs/images/tasks-provider.png" alt="Built-in tasks shown in task list" />
 </p>
 
-To learn about tasks in Visual Studio Code see [Integrate with External Tools via Tasks][3].
+!!! Info
+    To learn about tasks in Visual Studio Code see [Integrate with External Tools via Tasks][3].
 
-To use PSRule for Azure with the built-in `PSRule: Run analysis` task, insert the following into `.vscode/tasks.json`.
+### Customizing the task
 
-```json
+The _PSRule: Run analysis_ task will be available automatically after you install the PSRule extension.
+You can customize the defaults of the task by editing or inserting the task into `.vscode/tasks.json` within your workspace.
+
+```json title="JSON"
 {
     "type": "PSRule",
     "problemMatcher": [
@@ -46,7 +51,7 @@ To use PSRule for Azure with the built-in `PSRule: Run analysis` task, insert th
 !!! Example
     A complete `.vscode/tasks.json` might look like the following:
 
-    ```json
+    ```json title=".vscode/tasks.json"
     {
         "version": "2.0.0",
         "tasks": [

mkdocs.yml

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
 site_name: PSRule
 site_url: https://microsoft.github.io/PSRule
 site_description: Validate infrastructure as code (IaC) and objects using PowerShell rules.
@@ -133,7 +136,6 @@ plugins:
 - mkdocs-simple-hooks:
     hooks:
       on_page_markdown: "docs.hooks:replace_maml"
-      # on_nav: "docs.hooks:build_reference_nav"
 - search
 - git-revision-date
 - redirects:
@@ -153,10 +155,3 @@ extra:
     social_preview: https://repository-images.githubusercontent.com/125832556/d6685d9f-ba70-44a1-b11f-6534831143d1
     repo_issue: https://github.com/microsoft/PSRule/issues
     repo_discussion: https://github.com/microsoft/PSRule/discussions
-
-  # alternate:
-
-  #   # Switch to English
-  #   - name: English
-  #     link: /en/
-  #     lang: en

overrides/main.html

@@ -9,25 +9,32 @@
     {% set title = config.site_name ~ " - " ~ page.title | striptags %}
   {% endif %}
 
+  <!-- Determine description -->
+  {% set description = config.site_description %}
+  {% if page and page.meta and page.meta.description %}
+    {% set description = page.meta.description %}
+  {% endif %}
+
   <!-- The image needs to have an absolute URL -->
   {% set image = config.extra.local.social_preview %}
 
   <!-- Open graph meta tags -->
+  <meta property="og:site_name" content="{{ config.site_name }}" />
   <meta property="og:type" content="website" />
   <meta property="og:title" content="{{ title }}" />
-  <meta property="og:description" content="{{ config.site_description }}" />
+  <meta property="og:description" content="{{ description }}" />
   <meta property="og:url" content="{{ page.canonical_url }}" />
   <meta property="og:image" content="{{ image }}" />
   <meta property="og:image:type" content="image/png" />
   <meta property="og:image:width" content="1280" />
   <meta property="og:image:height" content="640" />
-  <meta property="og:image:alt" content="{{ config.site_description }}" />
+  <meta property="og:image:alt" content="{{ description }}" />
 
   <!-- Twitter meta tags -->
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:site" content="@github" />
   <meta name="twitter:title" content="{{ title }}" />
-  <meta name="twitter:description" content="{{ config.site_description }}" />
+  <meta name="twitter:description" content="{{ description }}" />
   <meta name="twitter:image" content="{{ image }}" />
 
 {% endblock %}