check-content/README.md

A tool for evaluating content against content standards.

# Atlassian content standards checker

A regex and AI-powered content standards linter that helps ensure your content meets our externally-pulisheed content standards, which inludes inclusive language, plain language, and accessibility standards. For this version of the linter, we're also incorporating California's plain language requirements.

## ✨ Features

- **🔍 Regex rules**: Fast pattern matching for common issues (gendered language, jargon, accessibility)
- **🤖 AI analysis**: Contextual analysis for tone, voice, and nuanced content issues
- **🎯 Quick wins**: Highlights high-impact, easy fixes
- **📈 Compliance scoring**: Track your content standards compliance

Look for:
- ❌ **Errors**: Must fix before shipping
- ⚠️ **Warnings**: Should fix for better user experience
- 🎯 **Quick wins**: Easy fixes for immediate improvement
- 📊 **Compliance score**: Track your progress

## 🎯 What it checks

### Regex rules (fast pattern matching)
- **Inclusive language**: Detects gendered terms, problematic language
- **Plain language**: Flags complex jargon and corporate speak
- **Accessibility**: Missing alt text, non-descriptive links
- **Pronouns**: Suggests gender-neutral alternatives

### AI analysis (contextual understanding)
- **Active voice**: Identifies passive voice usage
- **Content organization**: Non-descriptive button labels, unclear navigation
- **Tone consistency**: Brand voice alignment
- **User experience**: Content clarity and accessibility

## 📊 Example output

```
Content issues found:
==================================================

src/components/Header.tsx:
  📋 Regex rule violations:
    ❌ Use inclusive language [nonInclusiveTerms:line 12]
       → "guys" → everyone, team, folks
       "Welcome guys to our platform"

  🤖 AI content analysis:
    ⚠️ Use active voice (AI: Makes content clearer and more direct) [active_voice:line 15]
       → Our system processes the data automatically.
       "The data is processed by our system automatically."

Summary:
  🎉 Excellent! 85% standards compliance
  📋 Regex: 1 issue
  🤖 AI: 1 issue
  ❌ 1 error, ⚠️ 1 warning
  🎯 Quick win: Fix "guys" for instant improvement
  Analyzed 5 files
```

# Content standards linter - installation guide

## 🚀 Getting started

### Method 1: Install from package file (recommended for testing)

#### Step 1: Download and place the package file

1. **Download the package file** that was shared with you:
   - `Atlassian-content-standards-linter-1.0.0.tgz`

2. **Choose where to save it** (pick one):
   - **Desktop** (easiest): Save to your Desktop folder
   - **Downloads folder**: Usually `~/Downloads` on Mac/Linux or `C:\Users\YourName\Downloads` on Windows
   - **Project folder**: Save directly in your current project directory

#### Step 2: Navigate to the package location

Open your terminal/command prompt and navigate to where you saved the file:

**If saved to desktop:**
```bash
# Mac/Linux
cd ~/Desktop

# Windows
cd C:\Users\YourName\Desktop
```

**If saved to downloads:**
```bash
# Mac/Linux
cd ~/Downloads

# Windows  
cd C:\Users\YourName\Downloads
```

**If saved to your project folder:**
```bash
cd /path/to/your/project
# Example: cd ~/projects/my-react-app
```

#### Step 3: Verify the file is there
```bash
# List files to confirm the package is present
ls *.tgz                           # Mac/Linux
dir *.tgz                          # Windows

# You should see: yourcompany-content-standards-linter-1.0.0.tgz
```

#### Step 4: Install the package

```bash
# Install globally (recommended)
npm install -g ./Atlassian-content-standards-linter-1.0.0.tgz

# Alternative: If the above doesn't work, try with full filename
npm install -g Atlassian-content-standards-linter-1.0.0.tgz
```

#### Step 5: Test installation

```bash
# Check if it installed correctly
check-standards --version

# See all available options
check-standards --help
```

#### Step 6: Try it on your code

```bash
# Navigate to your project (if not already there)
cd /path/to/your/project

# Test on a single file
check-standards -i ./src/App.tsx

# Analyze your entire src directory  
check-standards -i ./src
```

### Method 2: Install without downloading

If the package is hosted somewhere accessible:

```bash
# Install from URL
npm install -g https://your-server.com/path/to/package.tgz

# Or from a shared network location
npm install -g //shared-drive/packages/content-standards-linter-1.0.0.tgz
```

### Method 3: Project-specific installation

If you want to add it to your project (not globally):

```bash
# Navigate to your project
cd /path/to/your/project

# Install locally
npm install --save-dev ./path/to/yourcompany-content-standards-linter-1.0.0.tgz

# Run with npx
npx check-standards -i ./src
```

## ✅ Verify installation

After installation, run these commands to confirm everything works:

```bash
# Check version
check-standards --version

# See all options
check-standards --help

# Test on a sample file (should work on any .tsx, .jsx, .js, or .html file)
check-standards -i ./src
```

## 🎯 Common use cases

### For React/TypeScript projects
```bash
# Analyze components
check-standards -i ./src/components

# Analyze pages
check-standards -i ./src/pages

# Full project scan
check-standards -i ./src
```

### For HTML/web projects
```bash
# Analyze HTML files
check-standards -i ./public

# Analyze specific files
check-standards -i ./index.html
```

### Development workflow integration
```bash
# Add to package.json scripts
{
  "scripts": {
    "lint:content": "check-standards -i ./src",
    "lint:content:errors": "check-standards -i ./src --severity error"
  }
}

# Then run with
npm run lint:content
```

## 🔧 Configuration options

### Basic options
```bash
# Only run fast regex checks (skip AI)
check-standards -i ./src --regex-only

# Only show errors (hide warnings)
check-standards -i ./src --severity error

# Output as JSON for CI/CD integration
check-standards -i ./src --format json
```

### Custom API endpoint
```bash
# Use different AI analysis endpoint
check-standards -i ./src --endpoint https://your-custom-api.com/analyze
```

## 🐛 Troubleshooting

### "command not found: check-standards"

**First, check where you are:**
```bash
pwd                    # Shows current directory
ls *.tgz              # Mac/Linux - should show the package file
dir *.tgz             # Windows - should show the package file
```

**Solution 1**: Make sure you're in the right directory
```bash
# Navigate to where you saved the .tgz file
cd ~/Desktop          # or wherever you saved it
ls *.tgz              # Confirm the file is there
npm install -g ./yourcompany-content-standards-linter-1.0.0.tgz
```

**Solution 2**: Reinstall globally
```bash
npm uninstall -g @yourcompany/content-standards-linter
npm install -g ./yourcompany-content-standards-linter-1.0.0.tgz
```

**Solution 3**: Use npx instead
```bash
npx check-standards -i ./src
```

**Solution 4**: Check your PATH
```bash
npm config get prefix
# Add that path to your shell's PATH variable
```

### "cannot find package './yourcompany-content-standards-linter-1.0.0.tgz'"

This means you're not in the right directory:

```bash
# Find where you saved the file
find ~ -name "*.tgz" 2>/dev/null | grep content-standards    # Mac/Linux
where /r C:\ *content-standards*.tgz                         # Windows

# Navigate to that directory
cd /path/to/where/file/is

# Then install
npm install -g ./yourcompany-content-standards-linter-1.0.0.tgz
```

### "No content found to analyze"

- Make sure you're pointing to files with supported extensions (.tsx, .jsx, .js, .html)
- Try with a specific file: `check-standards -i ./src/App.tsx`

### "Endpoint analysis failed"

- The AI analysis requires internet connection
- Use `--regex-only` flag to skip AI analysis: `check-standards -i ./src --regex-only`


## 🎉 You're ready!

Try running the linter on your current project:

```bash
check-standards -i ./src
```