Skip to main content

Local Verification Guide

This guide shows you how to run all the preview pipeline checks locally before committing and pushing to your remote branch.

📦 Prerequisites​

The required tools are already included as devDependencies in package.json:

  • markdownlint-cli - Markdown linting
  • cspell - Spell checking
  • svgo - SVG optimization

Install all dependencies:

npm install
# or
yarn install

After installation, you can run the tools using npx (no global installation needed).

Preview Pipeline Verification Steps​

The '**' pipeline (Test on a PR) runs these checks in order:

1. ✅ Markdown Linting​

What it checks: Markdown syntax violations (blank lines around lists, code block languages, etc.)

Run locally:

# Using npx (recommended - uses local devDependency)
npx markdownlint --ignore 'solutions/legacy' 'solutions/**/*.md*'

Quick fix: Use the automated fixer

node scripts/fix-markdown-linting.js --verbose

2. ✅ Spell Checking​

What it checks: Spelling errors in markdown files using a custom dictionary

Run locally:

# Using npx (recommended - uses local devDependency)
npx cspell lint --no-progress --config ./cspell.json "solutions/**/*.md*"

Fix spelling errors:

  • Fix typos in your content
  • Add technical terms to cspell.json if they're valid words: 
    {
      "words": [
        "TOTP",
        "FIPS",
        "your-technical-term"
      ]
    }

3. ✅ SVG Optimization​

What it checks: Optimizes SVG files for better performance

Run locally:

# Using npx (recommended - uses local devDependency)
# On macOS/Linux with fd installed
brew install fd  # or apt-get install fd-find on Linux
fd -e svg -0 | xargs -0 -P $(nproc) -n 10 npx svgo

# Alternative using find (works everywhere)
find . -name "*.svg" -type f -exec npx svgo {} \;

Note: This step modifies SVG files in place. Commit the optimized files.

4. ✅ Build the Site​

What it checks: Ensures the Docusaurus site builds without errors

Run locally:

# Set Node memory limit (important for large builds)
export NODE_OPTIONS="--max-old-space-size=12288"

# Build the site
yarn build

# Or with npm
npm run build

Common build errors:

  • Broken links
  • Missing images
  • Invalid front matter
  • TypeScript errors in custom components

5. ✅ Search Index Generation​

What it checks: Creates the search index for the site

Run locally:

# Generate search index
node scripts/build-search-index.js

Note: This creates build/search-index.json

6. ✅ Preview Environment Setup​

What it checks: Creates fallback API responses for preview deployment

Run locally:

# Set up preview environment
node scripts/deploy-preview.js

Note: This creates files in build/api/ directory

🚀 Quick Verification Script​

A verification script is included at scripts/local-verify.sh that runs all checks in sequence.

Usage:

# Make sure dependencies are installed first
npm install

# Run the verification script
./scripts/local-verify.sh

The script will:

  1. Check markdown linting
  2. Check spelling
  3. Optimize SVGs
  4. Build the site
  5. Generate search index
  6. Set up preview environment

All checks use the local devDependencies via npx, so no global installations are needed.

📋 Pre-Commit Checklist​

Before committing and pushing:

  • Run markdown linting: markdownlint --ignore 'solutions/legacy' 'solutions/**/*.md*'
  • Run spell check: cspell lint --no-progress --config ./cspell.json "solutions/**/*.md*"
  • Build the site: yarn build
  • Check for TypeScript errors: yarn typecheck (if applicable)
  • Test locally: yarn start and verify your changes
  • Review git diff: git diff to ensure only intended changes

🐛 Common Issues and Fixes​

Issue: Markdown linting fails​

Solution:

# Run the automated fixer
node scripts/fix-markdown-linting.js --verbose

# Then verify
npx markdownlint --ignore 'solutions/legacy' 'solutions/**/*.md*'

Issue: Spell check fails​

Solution:

  1. Fix actual typos in your content
  2. Add technical terms to cspell.json: 
    {
      "words": [
        "Eyeglass",
        "Cyberstorage",
        "PowerScale",
        "TOTP",
        "FIPS"
      ]
    }

Issue: Build fails with memory error​

Solution:

# Increase Node memory limit
export NODE_OPTIONS="--max-old-space-size=16384"
yarn build

Solution:

  • Check file paths in your markdown
  • Ensure linked files exist
  • Use relative paths correctly

Issue: TypeScript errors​

Solution:

# Run type checking
yarn typecheck

# Fix type errors in your code

🎯 Recommended Workflow​

  1. Install dependencies (first time only):

    npm install

  2. Make your changes to documentation files

  3. Fix markdown formatting:

    node scripts/fix-markdown-linting.js

  4. Run quick checks:

    npx markdownlint --ignore 'solutions/legacy' 'solutions/**/*.md*'
    npx cspell lint --no-progress --config ./cspell.json "solutions/**/*.md*"

  5. Test build:

    npm run build

  6. Preview locally:

    npm start
    # Open http://localhost:3000 and verify your changes

  7. Run full verification (optional but recommended):

    ./scripts/local-verify.sh

  8. Commit and push:

    git add .
    git commit -m "your commit message"
    git push

  9. Check pipeline in Bitbucket to see preview URL

📚 Additional Commands​

Serve production build locally​

# Build first
yarn build

# Serve (macOS/Linux)
yarn serve

# Serve (Windows)
yarn serve-win

Generate sitemap​

node scripts/generate-sitemap.js
node scripts/test-client-search.js

Run with search indexing​

npm run start-with-indexing

🔍 What the Pipeline Does NOT Check Locally​

These steps only run in the Bitbucket pipeline:

  1. Firebase deployment - Requires credentials
  2. Preview URL generation - Handled by Firebase hosting
  3. Pipeline artifacts - Stored in Bitbucket

Everything else can be verified locally before pushing!