Update utils

Standardize documentation and formatting

Author: uw-amy-bordenave

util/check-links.ps1

@@ -1,29 +1,43 @@
 #!/usr/bin/env pwsh
+# This script is designed to be run in a PowerShell environment.
+
+# Name: TCAT Wiki - Link Checker
+# Version: 1.0.1
+# Date: 2025-09-17
+# Author: Amy Bordenave, Taskar Center for Accessible Technology, University of Washington
+# License: CC-BY-ND 4.0 International
+
 <#
 .SYNOPSIS
-    Link validation script for TCAT Wiki documentation
+    Link validation script for the TCAT Wiki
 
 .DESCRIPTION
     Checks all .md files in the specified directory for broken internal and external links.
-    Returns exit code 0 if all links are valid, 1 if any links are broken.
+    Returns exit code 0 if all links are valid, 1 if any links are broken or there is an error.
 
 .PARAMETER docsPath
     Path to the documentation directory to scan (default: "docs")
 
 .PARAMETER verboseOutput
     Show verbose output during validation
 
+.PARAMETER internal
+    Check internal relative links
+
+.PARAMETER external
+    Check external absolute links
+
 .EXAMPLE
     .\check-links.ps1
-    Validates links in the default "docs" directory
+    Validates both internal and external links in the default "docs" directory
 
 .EXAMPLE
-    .\check-links.ps1 -docsPath "documentation" -verboseOutput
-    Validates links in "documentation" directory with verbose output
+    .\check-links.ps1 -verboseOutput -internal
+    Validates only internal relative links, with verbose output
 #>
 
 param(
-    [Parameter(HelpMessage = "Path to the documentation directory")]
+    [Parameter(HelpMessage = "Path to the docs directory")]
     [string]$docsPath = "",
 
     [Parameter(HelpMessage = "Show verbose output")]
@@ -79,9 +93,9 @@ if ($markdownFiles.Count -eq 0) {
 Write-Host "Found $($markdownFiles.Count) markdown files to validate" -ForegroundColor Green
 Write-Host ""
 
-$brokenInternalLinks = @()
-$brokenExternalLinks = @()
 $externalUrls = @{}
+$brokenExternalLinks = @()
+$brokenInternalLinks = @()
 
 # Function to extract links from markdown content
 function Get-MarkdownLinks {
@@ -133,7 +147,7 @@ function Test-InternalLink {
 function Test-ExternalUrlValid {
     param([string]$url)
 
-    # Skip known problematic domains that block automated requests
+    # Skip domains that block automated requests or are known to always fail
     $skipDomains = @(
         "*visualstudio.com*"
     )
@@ -142,7 +156,7 @@ function Test-ExternalUrlValid {
         if ($url -like $domain) {
             return @{
                 valid  = $true
-                status = "Skipped (known to block automated requests)"
+                status = "Skipped (known to block automated requests or always fail)"
             }
         }
     }

util/generate-guides-lists.ps1

@@ -1,7 +1,15 @@
 #!/usr/bin/env pwsh
+# This script is designed to be run in a PowerShell environment.
+
+# Name: TCAT Wiki - Guides Lists Generator
+# Version: 1.0.1
+# Date: 2025-09-17
+# Author: Amy Bordenave, Taskar Center for Accessible Technology, University of Washington
+# License: CC-BY-ND 4.0 International
+
 <#
 .SYNOPSIS
-    Generates index.md files for all guides directories in the docs folder.
+    Generates index.md files for all guides directories
 
 .DESCRIPTION
     This script recursively searches through the docs directory for any subdirectory 
@@ -144,7 +152,7 @@ function New-GuidesList {
 
     Write-Host "Processing guides directory: $GuidesPath"
 
-    # Get all .md files except index.md
+    # Get all .md files except main index.md
     $mdFiles = Get-ChildItem -Path $GuidesPath -Filter "*.md" | 
     Where-Object { $_.Name -ne "index.md" } |
     Sort-Object Name
@@ -404,8 +412,6 @@ foreach ($guidesDir in $guidesDirectories | Where-Object { $_.FullName -notmatch
     }
 }
 
-# No longer need miscellaneous section - misc guides are now in docs/misc/guides/
-
 # Write the master guides index
 $masterIndexPath = Join-Path $docsPath "guides-list" "index.md"
 $masterContent | Set-Content -Path $masterIndexPath -Encoding UTF8

util/generate-nav.ps1

@@ -1,4 +1,12 @@
 #!/usr/bin/env pwsh
+# This script is designed to be run in a PowerShell environment.
+
+# Name: TCAT Wiki - Navigation Section Generator
+# Version: 1.0.1
+# Date: 2025-09-17
+# Author: Amy Bordenave, Taskar Center for Accessible Technology, University of Washington
+# License: CC-BY-ND 4.0 International
+
 <#
 .SYNOPSIS
     Generates MkDocs navigation structure from docs directory
@@ -7,26 +15,20 @@
     Scans the docs directory structure and generates a YAML navigation tree 
     that can be inserted into mkdocs.yml. Uses frontmatter titles when available,
     otherwise derives titles from filenames and directory names.
+
 .PARAMETER docsPath
     Path to the documentation directory to scan (default: "docs")
 
-.PARAMETER outputFile
-    Output file path for the generated navigation YAML (default: console output)
+.PARAMETER mkdocsPath
+    Path to the mkdocs.yml file (default: "../mkdocs.yml")
 
 .PARAMETER updateMkdocs
     Update the mkdocs.yml file directly by replacing the nav section
 
-.PARAMETER mkdocsPath
-    Path to the mkdocs.yml file (default: "../mkdocs.yml")
-
 .EXAMPLE
     .\generate-nav.ps1
     Generates navigation and outputs to console
 
-.EXAMPLE
-    .\generate-nav.ps1 -outputFile "nav.yml"
-    Generates navigation and saves to nav.yml
-
 .EXAMPLE
     .\generate-nav.ps1 -updateMkdocs
     Updates mkdocs.yml directly with generated navigation
@@ -36,9 +38,6 @@ param(
     [Parameter(HelpMessage = "Path to the documentation directory")]
     [string]$docsPath = "",
 
-    [Parameter(HelpMessage = "Output file path for generated navigation")]
-    [string]$outputFile = "",
-    
     [Parameter(HelpMessage = "Update mkdocs.yml directly")]
     [switch]$updateMkdocs,
 
@@ -118,7 +117,7 @@ function Build-DirectoryNav {
     )
 
     $items = @()
-    $indent = "  " * $indentLevel
+    $indent = "    " * $indentLevel
 
     # Get directory name and relative path
     $dirInfo = Get-Item $dirPath
@@ -139,7 +138,7 @@ function Build-DirectoryNav {
 
     # Add index.md first if it exists
     if ($hasIndex) {
-        $subItems += "$indent  - $relativePath/index.md"
+        $subItems += "$indent    - $relativePath/index.md"
     }
 
     # Add other files in this directory
@@ -149,7 +148,7 @@ function Build-DirectoryNav {
         if (-not $fileTitle) {
             $fileTitle = ConvertTo-Title $file.BaseName
         }
-        $subItems += "$indent  - $($fileTitle): $fileRelativePath"
+        $subItems += "$indent    - $($fileTitle): $fileRelativePath"
     }
 
     # Add subdirectories
@@ -245,7 +244,7 @@ foreach ($file in $rootFiles) {
 
 # Generate final navigation YAML with proper indentation
 $indentedNavItems = $navItems | ForEach-Object { "  $_" }
-$navYaml = "nav:" + [Environment]::NewLine + ($indentedNavItems -join [Environment]::NewLine)
+$navYaml = "nav:" + [Environment]::NewLine + ($indentedNavItems -join [Environment]::NewLine) + [Environment]::NewLine
 
 # Output results
 if ($updateMkdocs) {
@@ -304,11 +303,6 @@ if ($updateMkdocs) {
     Set-Content -Path $mkdocsPath -Value $newContent -Encoding UTF8 -NoNewline
     Write-Host "Successfully updated mkdocs.yml navigation section" -ForegroundColor Green
 }
-elseif ($outputFile) {
-    # Save to output file
-    Set-Content -Path $outputFile -Value $navYaml -Encoding UTF8
-    Write-Host "Navigation saved to: $outputFile" -ForegroundColor Green
-}
 else {
     # Output to console
     Write-Host ""