This guide shows how to integrate the`docs-analysis` composite action with the existing`docs-preview-link.yml` workflow, eliminating duplication and consolidating documentation processing.

The docs-preview-link.yml workflow currently embeds document analysis functionality directly in the workflow steps, which leads to:

- Code duplication across workflows

- Harder maintenance when metrics need to be updated

- Inconsistent reporting between workflows

We can refactor the`docs-preview-link.yml` workflow to use our new composite action, bringing these benefits:

- Single source of truth for document analysis

- Consistent metrics across all documentation workflows

- Easier maintenance and feature additions

- Improved security and error handling

Here's how to replace the verify-docs-changes job in the docs-preview-link.yml workflow with our composite action:

verify-docs-changes:

needs:[validate-workflow, delay-start]

runs-on:ubuntu-latest

timeout-minutes:3# Reduced timeout for verification step

if:|

permissions:

contents:read

pull-requests:read

checks:write# For creating check runs

statuses:write# For creating commit statuses

if:|

outputs:

docs_changed:${{ steps.docs-analysis.outputs.docs-changed }}

pr_number:${{ steps.pr_info.outputs.pr_number }}

branch_name:${{ steps.pr_info.outputs.branch_name }}

repo_owner:${{ steps.pr_info.outputs.repo_owner }}

is_fork:${{ steps.pr_info.outputs.is_fork }}

is_comment:${{ steps.pr_info.outputs.is_comment }}

is_manual:${{ steps.pr_info.outputs.is_manual }}

skip:${{ steps.pr_info.outputs.skip }}

execution_start_time:${{ steps.timing.outputs.start_time }}

has_non_docs_changes:${{ steps.docs-analysis.outputs.has-non-docs-changes }}

words_added:${{ steps.docs-analysis.outputs.words-added }}

words_removed:${{ steps.docs-analysis.outputs.words-removed }}

docs_files_count:${{ steps.docs-analysis.outputs.docs-files-count }}

images_added:${{ steps.docs-analysis.outputs.images-added }}

manifest_changed:${{ steps.docs-analysis.outputs.manifest-changed }}

format_only:${{ steps.docs-analysis.outputs.format-only }}

steps:

-name:Capture start time

id:timing

run:|

-name:Harden Runner

uses:step-security/harden-runner@latest

with:

egress-policy:audit

-name:Create verification check run

id:create_check

uses:actions/github-script@latest

with:

github-token:${{ secrets.GITHUB_TOKEN }}

script:|

-name:Get PR info

id:pr_info

run:|

-name:Check out base repository code

if:steps.pr_info.outputs.skip != 'true'

uses:actions/checkout@latest

with:

ref:main# Always use the main branch

fetch-depth:5# Reduce checkout depth for faster runs

sparse-checkout:|

sparse-checkout-cone-mode:false

-name:Analyze documentation changes

id:docs-analysis

if:steps.pr_info.outputs.skip != 'true'

uses:./.github/actions/docs-analysis

with:

docs-path:${{ env.DOCS_PRIMARY_PATH }}

pr-ref:${{ steps.pr_info.outputs.branch_name }}

base-ref:'main'

significant-words-threshold:${{ env.SIGNIFICANT_WORDS_THRESHOLD }}

throttle-large-repos:'true'

debug-mode:${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug == 'true' || 'false' }}

-name:Update verification status

if:github.event_name == 'pull_request_target' || (github.event_name == 'workflow_dispatch' && steps.pr_info.outputs.skip != 'true')

uses:actions/github-script@latest

with:

github-token:${{ secrets.GITHUB_TOKEN }}

script:|

description:'Path to the documentation directory'

required:false

default:'docs/'

files-pattern:

description:'Glob pattern(s) for documentation files (use vertical bar | to separate multiple patterns)'

required:false

default:'**.md|docs/**'

changed-files:

description:'Comma-separated list of changed files (from tj-actions/changed-files)'

required:false

default:''

pr-ref:

description:'PR reference to analyze (e.g., refs/pull/123/head)'

required:false

description:'Base reference to compare against'

required:false

default:'main'

files-changed:

description:'Comma-separated list of files changed in PR'

required:false

default:''

max-scan-files:

description:'Maximum number of files to scan'

required:false

description:'Enable verbose debugging output'

required:false

default:'false'

use-changed-files-action:

description:'Whether to use tj-actions/changed-files instead of git commands'

required:false

default:'false'

outputs:

manifest-changed:

description:'Whether manifest.json was changed'

value:${{ steps.verify.outputs.manifest_changed }}

manifest-changed-files:

description:'List of files referenced in manifest changes'

value:${{ steps.verify.outputs.manifest_changed_files }}

format-only:

description:'Whether changes are formatting-only'

value:${{ steps.verify.outputs.format_only }}

significant-change:

description:'Whether changes are significant'

value:${{ steps.verify.outputs.significant_change }}

image-focused:

description:'Whether changes are focused on images'

value:${{ steps.verify.outputs.image_focused }}

has-non-docs-changes:

description:'Whether PR contains non-docs changes'

value:${{ steps.verify.outputs.has_non_docs_changes }}

changed-docs-files:

description:'List of changed docs files'

value:${{ steps.verify.outputs.changed_docs_files }}

docs-dir-files:

description:'List of changed files in docs directory'

value:${{ steps.verify.outputs.docs_dir_files }}

most-changed-file:

description:'Path to the most changed file'

value:${{ steps.find_changed_files.outputs.most_changed_file }}

-name:Analyze document structure

id:analyze_structure