MegaBites-AI/Windows-powershell

1# Verify Markdown Links Action2 3A GitHub composite action that verifies all links in markdown files using PowerShell and Markdig.4 5## Features6 7- ✅ Parses markdown files using Markdig (built into PowerShell 7)8- ✅ Extracts all link types: inline links, reference links, and autolinks9- ✅ Verifies HTTP/HTTPS links with configurable timeouts and retries10- ✅ Validates local file references11- ✅ Supports excluding specific URL patterns12- ✅ Provides detailed error reporting with file locations13- ✅ Outputs metrics for CI/CD integration14 15## Usage16 17### Basic Usage18 19```yaml20- name: Verify Markdown Links21  uses: ./.github/actions/infrastructure/markdownlinks22  with:23    path: './CHANGELOG'24```25 26### Advanced Usage27 28```yaml29- name: Verify Markdown Links30  uses: ./.github/actions/infrastructure/markdownlinks31  with:32    path: './docs'33    fail-on-error: 'true'34    timeout: 3035    max-retries: 236    exclude-patterns: '*.example.com/*,*://localhost/*'37```38 39### With Outputs40 41```yaml42- name: Verify Markdown Links43  id: verify-links44  uses: ./.github/actions/infrastructure/markdownlinks45  with:46    path: './CHANGELOG'47    fail-on-error: 'false'48 49- name: Display Results50  run: |51    echo "Total links: ${{ steps.verify-links.outputs.total-links }}"52    echo "Passed: ${{ steps.verify-links.outputs.passed-links }}"53    echo "Failed: ${{ steps.verify-links.outputs.failed-links }}"54    echo "Skipped: ${{ steps.verify-links.outputs.skipped-links }}"55```56 57## Inputs58 59| Input | Description | Required | Default |60|-------|-------------|----------|---------|61| `path` | Path to the directory containing markdown files to verify | No | `./CHANGELOG` |62| `exclude-patterns` | Comma-separated list of URL patterns to exclude from verification | No | `''` |63| `fail-on-error` | Whether to fail the action if any links are broken | No | `true` |64| `timeout` | Timeout in seconds for HTTP requests | No | `30` |65| `max-retries` | Maximum number of retries for failed requests | No | `2` |66 67## Outputs68 69| Output | Description |70|--------|-------------|71| `total-links` | Total number of unique links checked |72| `passed-links` | Number of links that passed verification |73| `failed-links` | Number of links that failed verification |74| `skipped-links` | Number of links that were skipped |75 76## Excluded Link Types77 78The action automatically skips the following link types:79 80- **Anchor links** (`#section-name`) - Would require full markdown parsing81- **Email links** (`mailto:user@example.com`) - Cannot be verified without sending email82 83## GitHub Workflow Test84 85This section provides a workflow example and instructions for testing the link verification action.86 87### Testing the Workflow88 89To test that the workflow properly detects broken links:90 911. Make change to this file (e.g., this README.md file already contains one in the [Broken Link Test](#broken-link-test) section)921. The workflow will run and should fail, reporting the broken link(s)931. Revert your change to this file941. Push again to verify the workflow passes95 96### Example Workflow Configuration97 98```yaml99name: Verify Links100 101on:102  push:103    branches: [ main ]104    paths:105      - '**/*.md'106  pull_request:107    branches: [ main ]108    paths:109      - '**/*.md'110  schedule:111    # Run weekly to catch external link rot112    - cron: '0 0 * * 0'113 114jobs:115  verify-links:116    runs-on: ubuntu-latest117    steps:118      - name: Checkout119        uses: actions/checkout@v4120 121      - name: Verify CHANGELOG Links122        uses: ./.github/actions/infrastructure/markdownlinks123        with:124          path: './CHANGELOG'125          fail-on-error: 'true'126 127      - name: Verify Documentation Links128        uses: ./.github/actions/infrastructure/markdownlinks129        with:130          path: './docs'131          fail-on-error: 'false'132          exclude-patterns: '*.internal.example.com/*'133```134 135## How It Works136 1371. **Parse Markdown**: Uses `Parse-MarkdownLink.ps1` to extract all links from markdown files using Markdig1382. **Deduplicate**: Groups links by URL to avoid checking the same link multiple times1393. **Verify Links**:140   - HTTP/HTTPS links: Makes HEAD/GET requests with configurable timeout and retries141   - Local file references: Checks if the file exists relative to the markdown file142   - Excluded patterns: Skips links matching the exclude patterns1434. **Report Results**: Displays detailed results with file locations for failed links1445. **Set Outputs**: Provides metrics for downstream steps145 146## Error Output Example147 148```149✗ FAILED: https://example.com/broken-link - HTTP 404150    Found in: /path/to/file.md:42:15151    Found in: /path/to/other.md:100:20152 153Link Verification Summary154============================================================155Total URLs checked: 150156Passed: 145157Failed: 2158Skipped: 3159 160Failed Links:161  • https://example.com/broken-link162    Error: HTTP 404163    Occurrences: 2164```165 166## Requirements167 168- PowerShell 7+ (includes Markdig)169- Runs on: `ubuntu-latest`, `windows-latest`, `macos-latest`170 171## Broken Link Test172 173- [Broken Link](https://github.com/PowerShell/PowerShell/wiki/NonExistentPage404)174 175## License176 177Same as the PowerShell repository.178