Skip to content

Commit ceeb1f8

Browse files
josbeirjosbeir
committed
Initial attempt reusable workflow
1 parent f904caa commit ceeb1f8

File tree

2 files changed

+239
-103
lines changed

2 files changed

+239
-103
lines changed

‎.github/workflows/docs-validation-reusable.yml‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
name: Reusable Documentation Validation
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
docs-path:
7+
description: 'Path to the docs directory (e.g. "docs/")'
8+
required: false
9+
type: string
10+
default: 'docs/'
11+
markdown-glob:
12+
description: 'Glob pattern for markdown files'
13+
required: false
14+
type: string
15+
default: 'docs/**/*.md'
16+
enable-toc-check:
17+
description: 'Enable TOC link validation (requires .vitepress/toc_*.json)'
18+
required: false
19+
type: boolean
20+
default: false
21+
enable-config-js-check:
22+
description: 'Enable .vitepress/config.js syntax check'
23+
required: false
24+
type: boolean
25+
default: false
26+
enable-json-lint:
27+
description: 'Enable TOC JSON file validation'
28+
required: false
29+
type: boolean
30+
default: false
31+
enable-spell-check:
32+
description: 'Enable spell checking'
33+
required: false
34+
type: boolean
35+
default: true
36+
enable-markdown-lint:
37+
description: 'Enable markdown linting'
38+
required: false
39+
type: boolean
40+
default: true
41+
enable-link-check:
42+
description: 'Enable internal link checking'
43+
required: false
44+
type: boolean
45+
default: true
46+
cspell-config:
47+
description: 'Path to cspell config file (relative to caller repo). Leave empty to use default from cakephp/docs.'
48+
required: false
49+
type: string
50+
default: ''
51+
markdownlint-config:
52+
description: 'Path to markdownlint config file (relative to caller repo). Leave empty to use default from cakephp/docs.'
53+
required: false
54+
type: string
55+
default: ''
56+
linkchecker-baseline:
57+
description: 'Path to link checker baseline JSON (relative to caller repo). Leave empty for no baseline.'
58+
required: false
59+
type: string
60+
default: ''
61+
docs-repo-ref:
62+
description: 'Branch/tag of cakephp/docs to use for shared validation scripts and default configs'
63+
required: false
64+
type: string
65+
default: '5.x'
66+
67+
jobs:
68+
js-lint:
69+
name: Validate config.js
70+
runs-on: ubuntu-latest
71+
if: ${{ inputs.enable-config-js-check }}
72+
steps:
73+
- name: Checkout code
74+
uses: actions/checkout@v6
75+
76+
- name: Validate config.js syntax
77+
run: node --check .vitepress/config.js
78+
79+
json-lint:
80+
name: Validate JSON Files
81+
runs-on: ubuntu-latest
82+
if: ${{ inputs.enable-json-lint }}
83+
steps:
84+
- name: Checkout code
85+
uses: actions/checkout@v6
86+
87+
- name: Validate JSON syntax
88+
run: |
89+
for file in .vitepress/toc_*.json; do
90+
if ! jq empty "$file" 2>/dev/null; then
91+
echo "Invalid JSON: $file"
92+
exit 1
93+
fi
94+
echo "Valid: $file"
95+
done
96+
97+
toc-link-check:
98+
name: Validate TOC Links
99+
runs-on: ubuntu-latest
100+
if: ${{ inputs.enable-toc-check }}
101+
steps:
102+
- name: Checkout code
103+
uses: actions/checkout@v6
104+
105+
- name: Checkout shared validation tools
106+
uses: actions/checkout@v6
107+
with:
108+
repository: cakephp/docs
109+
ref: ${{ inputs.docs-repo-ref }}
110+
path: .docs-tools
111+
sparse-checkout: |
112+
.github/check-toc-links.cjs
113+
114+
- name: Check TOC links exist
115+
run: node .docs-tools/.github/check-toc-links.cjs
116+
117+
markdown-lint:
118+
name: Lint Markdown
119+
runs-on: ubuntu-latest
120+
if: ${{ inputs.enable-markdown-lint }}
121+
steps:
122+
- name: Checkout code
123+
uses: actions/checkout@v6
124+
125+
- name: Checkout shared validation tools
126+
uses: actions/checkout@v6
127+
with:
128+
repository: cakephp/docs
129+
ref: ${{ inputs.docs-repo-ref }}
130+
path: .docs-tools
131+
sparse-checkout: |
132+
.github/.markdownlint-cli2.jsonc
133+
.github/markdownlint-rules
134+
135+
- name: Determine config path
136+
id: config
137+
run: |
138+
if [ -n "${{ inputs.markdownlint-config }}" ] && [ -f "${{ inputs.markdownlint-config }}" ]; then
139+
echo "path=${{ inputs.markdownlint-config }}" >> $GITHUB_OUTPUT
140+
else
141+
echo "path=.docs-tools/.github/.markdownlint-cli2.jsonc" >> $GITHUB_OUTPUT
142+
fi
143+
144+
- name: Lint markdown files
145+
uses: DavidAnson/markdownlint-cli2-action@v23
146+
with:
147+
config: ${{ steps.config.outputs.path }}
148+
globs: ${{ inputs.markdown-glob }}
149+
150+
spell-check:
151+
name: Spell Check
152+
runs-on: ubuntu-latest
153+
if: ${{ inputs.enable-spell-check }}
154+
steps:
155+
- name: Checkout code
156+
uses: actions/checkout@v6
157+
158+
- name: Checkout shared validation tools
159+
uses: actions/checkout@v6
160+
with:
161+
repository: cakephp/docs
162+
ref: ${{ inputs.docs-repo-ref }}
163+
path: .docs-tools
164+
sparse-checkout: |
165+
.github/cspell.json
166+
167+
- name: Determine config path
168+
id: config
169+
run: |
170+
if [ -n "${{ inputs.cspell-config }}" ] && [ -f "${{ inputs.cspell-config }}" ]; then
171+
echo "path=${{ inputs.cspell-config }}" >> $GITHUB_OUTPUT
172+
else
173+
echo "path=.docs-tools/.github/cspell.json" >> $GITHUB_OUTPUT
174+
fi
175+
176+
- name: Check spelling
177+
uses: streetsidesoftware/cspell-action@v8
178+
with:
179+
files: ${{ inputs.markdown-glob }}
180+
config: ${{ steps.config.outputs.path }}
181+
incremental_files_only: true
182+
183+
link-check:
184+
name: Check Internal Links
185+
runs-on: ubuntu-latest
186+
if: ${{ inputs.enable-link-check }}
187+
steps:
188+
- name: Checkout code
189+
uses: actions/checkout@v6
190+
with:
191+
fetch-depth: 0
192+
193+
- name: Checkout shared validation tools
194+
uses: actions/checkout@v6
195+
with:
196+
repository: cakephp/docs
197+
ref: ${{ inputs.docs-repo-ref }}
198+
path: .docs-tools
199+
sparse-checkout: |
200+
.github/check-links.cjs
201+
202+
- name: Get changed markdown files
203+
id: changed-files
204+
run: |
205+
if [ "${{ github.event_name }}" == "pull_request" ]; then
206+
FILES=$(git diff --name-only --diff-filter=d origin/${{ github.base_ref }}...HEAD | grep '\.md$' || true)
207+
if [ -z "$FILES" ]; then
208+
echo "No markdown files changed"
209+
echo "files=" >> $GITHUB_OUTPUT
210+
else
211+
echo "files=$(echo $FILES | tr '\n' ' ')" >> $GITHUB_OUTPUT
212+
echo "Checking files:"
213+
echo "$FILES"
214+
fi
215+
else
216+
echo "files=${{ inputs.markdown-glob }}" >> $GITHUB_OUTPUT
217+
echo "Checking all files: ${{ inputs.markdown-glob }}"
218+
fi
219+
220+
- name: Check internal links
221+
if: steps.changed-files.outputs.files != ''
222+
run: |
223+
BASELINE_ARG=""
224+
if [ -n "${{ inputs.linkchecker-baseline }}" ] && [ -f "${{ inputs.linkchecker-baseline }}" ]; then
225+
BASELINE_ARG="--baseline ${{ inputs.linkchecker-baseline }}"
226+
fi
227+
node .docs-tools/.github/check-links.cjs $BASELINE_ARG ${{ steps.changed-files.outputs.files }}

‎.github/workflows/docs-validation.yml‎

Lines changed: 12 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -19,106 +19,15 @@ on:
1919
- 'config.js'
2020

2121
jobs:
22-
js-lint:
23-
name: Validate JavaScript Files
24-
runs-on: ubuntu-latest
25-
26-
steps:
27-
- name: Checkout code
28-
uses: actions/checkout@v6
29-
30-
- name: Validate config.js syntax
31-
run: node --check .vitepress/config.js
32-
33-
json-lint:
34-
name: Validate JSON Files
35-
runs-on: ubuntu-latest
36-
37-
steps:
38-
- name: Checkout code
39-
uses: actions/checkout@v6
40-
41-
- name: Validate JSON syntax
42-
run: |
43-
for file in .vitepress/toc_*.json; do
44-
if ! jq empty "$file" 2>/dev/null; then
45-
echo "Invalid JSON: $file"
46-
exit 1
47-
fi
48-
echo "✅ Valid: $file"
49-
done
50-
51-
toc-link-check:
52-
name: Validate TOC Links
53-
runs-on: ubuntu-latest
54-
55-
steps:
56-
- name: Checkout code
57-
uses: actions/checkout@v6
58-
59-
- name: Check TOC links exist
60-
run: node .github/check-toc-links.cjs
61-
62-
markdown-lint:
63-
name: Lint Markdown
64-
runs-on: ubuntu-latest
65-
66-
steps:
67-
- name: Checkout code
68-
uses: actions/checkout@v6
69-
70-
- name: Lint markdown files
71-
uses: DavidAnson/markdownlint-cli2-action@v23
72-
with:
73-
config: './.github/.markdownlint-cli2.jsonc'
74-
globs: 'docs/**/*.md'
75-
76-
spell-check:
77-
name: Spell Check
78-
runs-on: ubuntu-latest
79-
80-
steps:
81-
- name: Checkout code
82-
uses: actions/checkout@v6
83-
84-
- name: Check spelling
85-
uses: streetsidesoftware/cspell-action@v8
86-
with:
87-
files: 'docs/**/*.md'
88-
config: '.github/cspell.json'
89-
incremental_files_only: true
90-
91-
link-check:
92-
name: Check Internal Links
93-
runs-on: ubuntu-latest
94-
95-
steps:
96-
- name: Checkout code
97-
uses: actions/checkout@v6
98-
with:
99-
fetch-depth: 0
100-
101-
- name: Get changed markdown files
102-
id: changed-files
103-
run: |
104-
if [ "${{ github.event_name }}" == "pull_request" ]; then
105-
# Get files changed in PR
106-
FILES=$(git diff --name-only --diff-filter=d origin/${{ github.base_ref }}...HEAD | grep '\.md$' || true)
107-
if [ -z "$FILES" ]; then
108-
echo "No markdown files changed"
109-
echo "files=" >> $GITHUB_OUTPUT
110-
else
111-
# Convert to space-separated list for script
112-
echo "files=$(echo $FILES | tr '\n' ' ')" >> $GITHUB_OUTPUT
113-
echo "Checking files:"
114-
echo "$FILES"
115-
fi
116-
else
117-
# For push events, check all files using glob pattern
118-
echo 'files="docs/**/*.md"' >> $GITHUB_OUTPUT
119-
echo 'Checking all files: docs/**/*.md'
120-
fi
121-
122-
- name: Check internal links
123-
if: steps.changed-files.outputs.files != ''
124-
run: node .github/check-links.cjs --baseline .github/linkchecker-baseline.json ${{ steps.changed-files.outputs.files }}
22+
validate:
23+
uses: cakephp/docs/.github/workflows/docs-validation-reusable.yml@5.x
24+
with:
25+
enable-config-js-check: true
26+
enable-json-lint: true
27+
enable-toc-check: true
28+
enable-spell-check: true
29+
enable-markdown-lint: true
30+
enable-link-check: true
31+
markdownlint-config: '.github/.markdownlint-cli2.jsonc'
32+
cspell-config: '.github/cspell.json'
33+
linkchecker-baseline: '.github/linkchecker-baseline.json'

0 commit comments

Comments
 (0)