# SEO Internal Link Tool

A comprehensive SEO tool for Next.js applications that analyzes, optimizes, and reports on internal linking and SEO performance.

## Features

- **Page Discovery**: Automatically discovers React pages in the `app` directory
- **Sitemap Generation**: Creates XML sitemaps for search engines
- **Internal Link Analysis**: Analyzes existing internal links and identifies issues
- **Link Optimization**: Automatically optimizes internal links based on SEO rules
- **JSON-LD Structured Data**: Generates structured data for better search visibility
- **SEO Reports**: Generates comprehensive SEO reports with scoring
- **Interactive Mode**: Command-line interactive interface

## Installation

The tool is included with the project. No additional installation required.

## Usage

### Command Line Interface

```bash
# Generate sitemap
node scripts/seo-internal-link-tool.js sitemap --output artifacts/reports/sitemap.xml

# Analyze internal links
node scripts/internal-link-tool.js analyze --output artifacts/reports/report.json

# Optimize internal links
node scripts/seo-internal-link-tool.js optimize --output artifacts/reports/optimization.json

# Generate JSON-LD structured data
node scripts/seo-internal-link-tool.js json-ld --output artifacts/reports/json-ld-data.json

# Generate SEO report
node scripts/seo-internal-link-tool.js report --format json --output artifacts/reports/seo-report.json

# Start interactive mode
node scripts/seo-internal-link-tool.js interactive
```

### pnpm Scripts

The tool can also be run using pnpm scripts:

```bash
# Generate sitemap
pnpm seo:sitemap -- --output artifacts/reports/sitemap.xml

# Analyze internal links
pnpm seo:analyze -- --output artifacts/reports/report.json

# Generate SEO report
pnpm seo:report -- --format json --output artifacts/reports/seo-report.json

# Generate JSON-LD structured data
pnpm seo:json-ld -- --output artifacts/reports/json-ld-data.json
```

## Commands

### sitemap

Generates an XML sitemap from React pages.

```bash
node scripts/seo-internal-link-tool.js sitemap [--output artifacts/reports/sitemap.xml]
```

### analyze

Analyzes internal links and identifies issues like orphaned pages and broken links.

```bash
node scripts/seo-internal-link-tool.js analyze [--output artifacts/reports/report.json] [--format json|html|csv|markdown]
```

### optimize

Optimizes internal links based on predefined rules and keywords.

```bash
node scripts/seo-internal-link-tool.js optimize [--output artifacts/reports/optimization.json]
```

### json-ld

Generates JSON-LD structured data for better search engine visibility.

```bash
node scripts/seo-internal-link-tool.js json-ld [--output artifacts/reports/json-ld-data.json]
```

### report

Generates a comprehensive SEO report with scoring.

```bash
node scripts/seo-internal-link-tool.js report [--output artifacts/reports/seo-report.json] [--format json|markdown|html]
```

### interactive

Starts an interactive command-line interface.

```bash
node scripts/seo-internal-link-tool.js interactive
```

## Configuration

The tool uses a configuration system defined in `lib/internal-link-config.js` which includes:

- **Business Information**: Company name and website URL
- **Priority Links**: Pages that should be prioritized for internal linking
- **Keyword Mappings**: Automatic linking of specific keywords to target pages
- **Page-specific Rules**: Configuration for different types of pages
- **Link Density Rules**: Limits and guidelines for link placement
- **SEO Scoring Weights**: How different SEO factors contribute to overall scores

## Output Formats

### JSON

Machine-readable format for programmatic analysis.

### Markdown

Human-readable format for documentation and reports.

### HTML

Interactive reports with styling for web viewing.

### CSV

Tabular format for spreadsheet analysis.

## Example Output

### Sitemap Generation

```
==================================================
  Generating Sitemap from React Pages
==================================================
✓ Found 37 pages
✓ Sitemap saved to: sitemap.xml
✓ Default sitemap location: /out/sitemap.xml
```

### Link Analysis

```
==================================================
  Analyzing Internal Links
==================================================
📊 Link Analysis Summary
Total Pages: 37
Internal Links: 7
Average Link Density: 7.00 links per page

⚠ Orphaned Pages: 36
  - about-us/
  - contact-us/
  - services/
  - etc.
```

### SEO Report

```
==================================================
  Generating SEO Report
==================================================
📊 SEO Analysis Summary
Total Pages Analyzed: 37
Average SEO Score: 0.5/100

🏆 Top Performing Pages:
1. services/parts/ - Score: 0.7
2. manuals/ - Score: 0.7
3. about-us/ - Score: 0.6
```

## File Structure

```
scripts/
├── seo-internal-link-tool.js      # Main CLI tool
├── lighthouse-test.js            # Performance testing (existing)
└── generate-internal-links.js     # Link generation (existing)

lib/
├── seo-utils.js                   # Page discovery and analysis
└── internal-link-config.js        # SEO configuration

public/
└── json-ld/                       # Generated JSON-LD files
```

## Integration

The tool is designed to integrate seamlessly with existing Next.js workflows:

1. **Discovery**: Automatically finds pages in the `app` directory
2. **Analysis**: Works with existing React components
3. **Output**: Generates files under `artifacts/reports/` to keep the repo root clean
4. **Configuration**: Customizable through the config system

## Troubleshooting

### Common Issues

1. **Module not found**: Ensure all files are in the correct location
2. **Permission denied**: Check file permissions for output directories
3. **Empty results**: Verify the `app` directory contains page components

### Debug Mode

Use the `--verbose` flag for detailed output:

```bash
node scripts/seo-internal-link-tool.js sitemap --verbose
```

## Contributing

The tool is designed to be extensible. Key areas for enhancement:

- **Additional SEO Metrics**: Expand the scoring system
- **Custom Rules**: Add support for custom link optimization rules
- **Integration**: Add support for other frameworks and platforms
- **Reporting**: Extend the reporting system with more visualizations