docs(cli): a project-local install adds a dependency, it does not pin… #913

Workflow file for this run

	name: Documentation

	on:
	push:
	branches: [ main ]
	paths:
	- 'docs/**'
	- 'res/**'
	- 'package.json'
	- 'packages/*/.ts'
	- 'packages/*/.tsx'
	- 'typedoc.json'
	- 'scripts/generate-api-docs.cjs'
	- 'scripts/sync-brand-assets.mjs'
	- '.github/workflows/docs.yml'
	pull_request:
	branches: [ main, next ]
	paths:
	- 'docs/**'
	- 'res/**'
	- 'package.json'
	- 'packages/*/.ts'
	- 'packages/*/.tsx'
	- 'typedoc.json'
	- 'scripts/generate-api-docs.cjs'
	- 'scripts/sync-brand-assets.mjs'
	# Allow manual triggering
	workflow_dispatch:

	# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
	permissions:
	contents: read
	pages: write
	id-token: write
	pull-requests: write
	issues: write

	# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
	# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
	concurrency:
	group: "pages"
	cancel-in-progress: false

	jobs:
	# Build job
	build:
	runs-on: ubuntu-latest
	env:
	GITHUB_TOKEN: ${{ github.token }}
	steps:
	- name: Checkout
	uses: actions/checkout@v4
	with:
	fetch-depth: 0

	- name: Setup Node.js
	uses: actions/setup-node@v4
	with:
	node-version: '22'

	- name: Install pnpm
	uses: pnpm/action-setup@v2
	with:
	version: 10

	- name: Install root dependencies
	run: npm install

	- name: Resolve n8n stable tag
	id: n8n-tag
	run: echo "tag=$(node scripts/ensure-n8n-cache.cjs --print-tag)" >> "$GITHUB_OUTPUT"

	- name: Cache n8n repository
	uses: actions/cache@v4
	with:
	path: .n8n-cache
	key: ${{ runner.os }}-n8n-cache-${{ steps.n8n-tag.outputs.tag }}-${{ hashFiles('scripts/ensure-n8n-cache.cjs') }}
	restore-keys: \|
	${{ runner.os }}-n8n-cache-

	- name: Build packages
	run: npm run build

	- name: Install docs dependencies
	working-directory: ./docs
	run: npm install

	- name: Generate API documentation
	run: npm run docs:api

	- name: Build documentation
	working-directory: ./docs
	run: npm run build

	- name: Setup Pages
	if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
	uses: actions/configure-pages@v4

	- name: Upload artifact
	if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
	uses: actions/upload-pages-artifact@v3
	with:
	path: ./docs/build

	- name: Run documentation tests
	run: \|
	# Check if documentation builds successfully
	if [ ! -d "./docs/build" ]; then
	echo "Documentation build failed - build directory not found"
	exit 1
	fi

	# Check for broken links (basic check)
	echo "Checking for broken internal links..."
	# We exclude 404.html because it naturally contains "Page Not Found"
	find ./docs/build -name "*.html" -type f ! -name "404.html" \| head -20 \| while read file; do
	echo "Checking $file"
	if grep -q "Page Not Found" "$file"; then
	echo "ERROR: Found 'Page Not Found' in $file"
	exit 1
	fi
	done

	echo "Documentation build validation passed"

	# Deployment job
	deploy:
	environment:
	name: github-pages
	url: ${{ steps.deployment.outputs.page_url }}
	runs-on: ubuntu-latest
	needs: build
	if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
	steps:
	- name: Deploy to GitHub Pages
	id: deployment
	uses: actions/deploy-pages@v4

	# Documentation validation job (runs on PRs)
	validate:
	env:
	GITHUB_TOKEN: ${{ github.token }}
	runs-on: ubuntu-latest
	if: github.event_name == 'pull_request'
	steps:
	- name: Checkout
	uses: actions/checkout@v4

	- name: Setup Node.js
	uses: actions/setup-node@v4
	with:
	node-version: '22'

	- name: Install pnpm
	uses: pnpm/action-setup@v2
	with:
	version: 10

	- name: Install root dependencies
	run: npm install

	- name: Install docs dependencies
	working-directory: ./docs
	run: npm install

	- name: Validate documentation structure
	run: \|
	echo "Validating documentation structure..."

	# Check required directories exist
	required_dirs=(
	"docs/docs/home"
	"docs/docs/getting-started"
	"docs/docs/usage"
	"docs/docs/contribution"
	"docs/docs/community"
	)

	for dir in "${required_dirs[@]}"; do
	if [ ! -d "$dir" ]; then
	echo "ERROR: Required directory $dir not found"
	exit 1
	fi
	done

	# Check required configuration files
	required_files=(
	"docs/docusaurus.config.ts"
	"docs/sidebars.ts"
	"docs/sidebars.api.ts"
	"docs/src/css/custom.css"
	)

	for file in "${required_files[@]}"; do
	if [ ! -f "$file" ]; then
	echo "ERROR: Required file $file not found"
	exit 1
	fi
	done

	echo "Documentation structure validation passed"

	- name: TypeScript type checking
	working-directory: ./docs
	run: npm run typecheck

	- name: Check for broken links in markdown
	run: \|
	echo "Checking for broken markdown links..."
	# Install markdown link checker if not present
	if ! command -v markdown-link-check &> /dev/null; then
	npm install -g markdown-link-check
	fi

	# Check a subset of markdown files
	find docs/docs -name "*.md" -type f \| head -10 \| while read file; do
	echo "Checking $file"
	markdown-link-check "$file" --config .github/markdown-link-check-config.json 2>/dev/null \|\| true
	done

	- name: Generate API documentation (dry run)
	run: npm run docs:api -- --dry-run 2>/dev/null \|\| echo "API generation check completed"

	- name: Comment on PR with documentation preview
	if: always()
	uses: actions/github-script@v7
	with:
	script: \|
	const { owner, repo } = context.repo;
	const prNumber = context.payload.pull_request.number;

	const success = '${{ job.status }}' === 'success';
	const message = success
	? `✅ Documentation validation passed! The documentation changes look good.\n\nOnce merged, the documentation will be automatically deployed to GitHub Pages.`
	: `❌ Documentation validation failed. Please check the workflow logs for details.`;

	await github.rest.issues.createComment({
	owner,
	repo,
	issue_number: prNumber,
	body: `## Documentation Validation\n\n${message}\n\nWorkflow: ${{ github.workflow }} #${{ github.run_id }}`
	});

Navigation Menu

Uh oh!

docs(cli): a project-local install adds a dependency, it does not pin… #913

Workflow file

docs(cli): a project-local install adds a dependency, it does not pin… #913

Uh oh!

Workflow file for this run