ocp-doc-checker

README

ocp-doc-checker

A tool to check if OpenShift Container Platform (OCP) documentation URLs are outdated and suggest newer versions.

Features

• ✅ Check single OCP documentation URLs
• 📁 Scan files and directories for OCP URLs
• 🔧 Automatically fix outdated URLs in files
• 📊 JSON output for automation
• 🎯 GitHub Action for CI/CD integration
• 🔍 Batch processing with detailed reports

Installation

Binary

Build from source:

git clone https://github.com/sebrandon1/ocp-doc-checker.git
cd ocp-doc-checker
make build

The binary will be created as ocp-doc-checker in the current directory.

GitHub Action

Add to your workflow (see GitHub Action Usage below).

CLI Usage

Basic Commands

Check a single URL

./ocp-doc-checker -url "https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html-single/disconnected_environments/index#mirroring-image-set-full"

Scan a directory for OCP URLs

./ocp-doc-checker -dir ./docs

Scan a single file

./ocp-doc-checker -dir ./README.md

Automatically fix outdated URLs

./ocp-doc-checker -dir ./docs -fix

This will:

1. Find all OCP documentation URLs in the directory
2. Check which ones are outdated
3. Automatically update them to the latest version in place

CLI Flags

Flag	Description	Default
-url	Single OCP documentation URL to check	-
-dir	Directory or file to scan for OCP URLs	-
-fix	Automatically fix outdated URLs in files (requires -dir)	false
-json	Output results in JSON format	false
-verbose	Enable verbose output	false
-all-available	Show all available newer versions (default: latest only)	false
-version	Print version information	-

Examples

Show all available newer versions

./ocp-doc-checker -url "https://docs.redhat.com/..." -all-available

Get JSON output for automation

./ocp-doc-checker -url "https://docs.redhat.com/..." -json

Scan and fix with verbose output

./ocp-doc-checker -dir ./docs -fix -verbose

Exit Codes

• 0: All URLs are up-to-date, or -fix was used successfully
• 1: Outdated URLs found (when not using -fix), or error occurred

GitHub Action Usage

Basic Example - Check Single URL

name: Check Documentation
on: [pull_request]

jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check OCP Documentation URL
        uses: sebrandon1/ocp-doc-checker@v1
        with:
          url: 'https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html-single/disconnected_environments/index#mirroring-image-set-full'
          fail-on-outdated: true

Scan Files and Directories

- name: Scan documentation files
  uses: sebrandon1/ocp-doc-checker@v1
  with:
    paths: 'docs/ README.md CONTRIBUTING.md'
    fail-on-outdated: true

Automatically Fix Outdated URLs

- name: Fix outdated documentation URLs
  uses: sebrandon1/ocp-doc-checker@v1
  with:
    paths: 'docs/ README.md'
    fix: true

In conjunction with a PR creation action, this can create a powerful tool to automatically fix your outdated URLs.

This will automatically update any outdated OCP documentation URLs in the specified files to their latest versions. When fix is enabled, the action won't fail even if outdated URLs were found (since they've been fixed).

Non-Blocking Check

- name: Check documentation (warning only)
  uses: sebrandon1/ocp-doc-checker@v1
  with:
    paths: 'docs/'
    fail-on-outdated: false

With All Available Versions

- name: Check with all versions
  uses: sebrandon1/ocp-doc-checker@v1
  with:
    url: 'https://docs.redhat.com/...'
    all-available: true
    verbose: true

Action Inputs

Input	Description	Required	Default
url	Single OCP documentation URL to check	No	-
paths	Space-separated list of files/directories to scan	No	-
fail-on-outdated	Fail the action if outdated URLs are found	No	true
all-available	Show all available newer versions	No	false
verbose	Enable verbose output	No	false
fix	Automatically fix outdated URLs in files (only works with paths)	No	false

Note: Either url or paths must be specified, but not both. The fix option can only be used with paths.

Action Outputs

Single URL Mode

Output	Description
is-outdated	Whether the URL is outdated (true/false)
latest-version	The latest version where the doc exists (e.g., 4.19)
newer-versions	JSON array of newer versions

Batch Mode (paths)

Output	Description
is-outdated	Whether any URLs are outdated (true/false)
outdated-count	Number of outdated URLs found
uptodate-count	Number of up-to-date URLs found
total-count	Total number of URLs checked

Using Outputs

- name: Check documentation
  id: doc-check
  uses: sebrandon1/ocp-doc-checker@v1
  with:
    url: 'https://docs.redhat.com/...'
    fail-on-outdated: false

- name: Use outputs
  run: |
    echo "Is outdated: ${{ steps.doc-check.outputs.is-outdated }}"
    echo "Latest version: ${{ steps.doc-check.outputs.latest-version }}"

JSON Output Format

Single URL

{
  "original_url": "https://docs.redhat.com/.../4.17/...",
  "original_version": "4.17",
  "latest_version": "4.19",
  "is_outdated": true,
  "newer_versions": [
    {
      "version": "4.18",
      "url": "https://docs.redhat.com/.../4.18/..."
    },
    {
      "version": "4.19",
      "url": "https://docs.redhat.com/.../4.19/..."
    }
  ]
}

Development

Build

make build

Run Tests

# Run all tests (unit + integration)
make test

# Run only Go unit tests
make test-unit

# Run only integration tests
make test-integration

# Run all CI tests
make test-ci

Format and Lint

# Format code
make fmt

# Run linters
make lint

Install Locally

make install

This installs the binary to $GOPATH/bin.

How It Works

1. URL Parsing: Extracts OCP version and document structure from Red Hat documentation URLs
2. Version Discovery: Checks newer OCP versions to see if the same document exists
3. URL Validation: Verifies that suggested URLs are accessible (HTTP HEAD/GET requests)
4. Smart Recommendations: Only suggests versions where the exact document and anchor exist

Supported URL Formats

The tool supports Red Hat OpenShift Container Platform documentation URLs in the following formats:

• https://docs.redhat.com/en/documentation/openshift_container_platform/{version}/html-single/{document}/index#{anchor}
• https://docs.redhat.com/en/documentation/openshift_container_platform/{version}/html/{document}/{page}#{anchor}

Examples:

• Single-page HTML: .../4.17/html-single/disconnected_environments/index#anchor
• Multi-page HTML: .../4.17/html/telco_ref_design_specs/telco-hub-ref-design-specs#anchor

License

MIT License - see LICENSE file for details.

Author

Brandon Palm

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.