@@ -77,33 +77,83 @@ pnpm install
7777The documentation workflow system has a clear separation of concerns with multiple layers:
7878
7979```
80- ┌─ Workflow Entry Points ─────────────────────────────────┐
81- │ │
82- │ PR Preview Post-Merge Weekly CI Check │
83- │ Workflow Validation Checks Workflow │
84- │ │
85- └───────────────────┬─────────────────────────────────────┘
86- │
87- ▼
88- ┌─ Unified Reusable Workflow ─────────────────────────────┐
89- │ │
90- │ docs-unified.yaml │
91- │ - Configuration presets (PR, post-merge, weekly, CI) │
92- │ - Conditional dependency installation │
93- │ - Single source of truth for all validation │
94- │ │
95- └───────────────────┬─────────────────────────────────────┘
96- │
97- ▼
98- ┌─ Core Implementation ────────────────────────────────────┐
99- │ │
100- │ docs-core/action.yaml │
101- │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
102- │ │ File │ │ Validation │ │ Results │ │
103- │ │ Detection │ │ & Preview │ │ Processing │ │
104- │ └─────────────┘ └─────────────┘ └─────────────┘ │
105- │ │
106- └──────────────────────────────────────────────────────────┘
80+ ┌─ Workflow Entry Points ───────────────────────────────────────────────────────┐
81+ │ │
82+ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌───────────┐ │
83+ │ │ PR Preview │ │ Post-Merge │ │ Weekly │ │ CI Check │ │
84+ │ │ Workflow │ │ Validation │ │ Checks │ │ Workflow │ │
85+ │ │ docs-preview.yml│ │ docs-ci.yml │ │weekly-docs.yml │ │docs-ci.yml│ │
86+ │ │ │ │ │ │ │ │ │ │
87+ │ │ • Runs on PR │ │ • Runs after │ │ • Runs weekly │ │ • Runs on │ │
88+ │ │ creation/update│ │ merges to main│ │ on schedule │ │ PR │ │
89+ │ │ • Generates │ │ • Checks links │ │ • Comprehensive │ │ • Basic │ │
90+ │ │ preview links │ │ only │ │ validation │ │ checks │ │
91+ │ │ • Validates docs│ │ • Falls back to │ │ • Creates issues│ │ • Fast │ │
92+ │ │ • Posts comments│ │ original doc │ │ for problems │ │ feedback│ │
93+ │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ └─────┬─────┘ │
94+ │ │ │ │ │ │
95+ └───────────┼────────────────────┼────────────────────┼──────────────────┼───────┘
96+ │ │ │ │
97+ └──────────┬─────────┴──────────┬─────────┴──────────┬──────┘
98+ │ │ │
99+ ▼ ▼ ▼
100+ ┌─ Unified Reusable Workflow ─────────────────────────────────────────────────────┐
101+ │ │
102+ │ docs-unified.yaml │
103+ │ ┌───────────────────────────────────────────────────────────────────────────┐ │
104+ │ │ Configuration System │ │
105+ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
106+ │ │ │ PR Preset │ │Post Preset │ │Weekly Preset│ │ CI Preset │ │ │
107+ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
108+ │ └───────────────────────────────────────────────────────────────────────────┘ │
109+ │ │
110+ │ ┌───────────────────────────────────────────────────────────────────────────┐ │
111+ │ │ Conditional Setup │ │
112+ │ │ • Tool installation (Node.js, PNPM, Vale) │ │
113+ │ │ • Comment posting system │ │
114+ │ │ • Notification handling │ │
115+ │ └───────────────────────────────────────────────────────────────────────────┘ │
116+ │ │
117+ └──────────────────────────────────────┬──────────────────────────────────────────┘
118+ │
119+ ▼
120+ ┌─ Core Implementation (docs-core/action.yaml) ───────────────────────────────────┐
121+ │ │
122+ │ ┌─── Phase 1: Setup & Detection ───┐ ┌─── Phase 3: Validation ─────────────┐ │
123+ │ │ │ │ │ │
124+ │ │ • Configuration processing │ │ • Markdown linting │ │
125+ │ │ • Environment validation │ │ • Table format checking │ │
126+ │ │ • Changed file detection │ │ • Link validation │ │
127+ │ │ • Advanced fallback mechanisms │ │ • Vale style checking (parallel) │ │
128+ │ │ • File relevance prioritization │ │ • Enhanced cross-reference checks │ │
129+ │ └──────────────────────────────────┘ └──────────────────────────────────────┘ │
130+ │ │
131+ │ ┌─── Phase 4: Results & Reporting ──────────────────────────────────────────┐ │
132+ │ │ │ │
133+ │ │ • Results aggregation and normalization │ │
134+ │ │ • JSON-based validation tracking │ │
135+ │ │ • Two-stage PR comment system │ │
136+ │ │ • Issue reporting │ │
137+ │ │ • Statistics calculation │ │
138+ │ └───────────────────────────────────────────────────────────────────────────┘ │
139+ │ │
140+ └─────────────────────────────────────────────────────────────────────────────────┘
141+ │
142+ ▼
143+ ┌─ Local Development Integration ────────────────────────────────────────────────┐
144+ │ │
145+ │ Makefile targets that mirror workflow functionality: │
146+ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
147+ │ │ make lint/docs│ │make fmt/markdown│ │make lint/markdown│ │make lint/docs-style│ │
148+ │ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │
149+ │ │
150+ │ Features: │
151+ │ • Automatically detects changed files (git diff) │
152+ │ • Supports both changed-only (default) and all-files (--all) modes │
153+ │ • Uses same validation tools as GitHub Actions │
154+ │ • Provides clear error messages and fix instructions │
155+ │ │
156+ └───────────────────────────────────────────────────────────────────────────────┘
107157```
108158
109159##Documentation Workflow Components