# General

SleekRank is a programmatic page generation plugin for WordPress that lets you create hundreds of unique pages from a single template and a data source. Instead of manually creating each page, you define a pattern and let SleekRank do the rest.

## Core Concept

The fundamental idea behind SleekRank is simple: take a **base page**, combine it with a **data source**, and generate **unique pages** with their own URLs, content, and meta tags — all without creating actual posts in your database.

## How It Works

SleekRank introduces the concept of **Page Groups**. Each page group defines:

- **Base Page**: A regular WordPress page that serves as the template
- **URL Pattern**: A dynamic URL structure with placeholders (e.g., `/services/{city}/`)
- **Data Source**: A JSON URL or JSON file that provides the data
- **Replacements**: Rules for swapping content, selectors, lists, and meta tags

When a visitor requests a URL that matches your pattern, SleekRank resolves it dynamically — fetching the corresponding data entry, applying replacements, and serving a fully formed page.

## Key Features

- **Dynamic Page Generation**: Create hundreds of pages from a single template
- **Multiple Data Sources**: Fetch from APIs (JSON URL) or load local files (JSON File)
- **Flexible Replacements**: Tag, CSS selector, list, and meta replacement types
- **SEO Integration**: Automatic sitemap entries for all major SEO plugins
- **Theme Sync**: Bidirectional sync between theme JSON files and the database
- **No Database Bloat**: Pages are generated on-the-fly, not stored as posts

## Use Cases

Programmatic page generation is ideal for creating large sets of similar but unique pages:

- Location-based landing pages (e.g., "Services in {city}")
- Product pages from external API data
- Keyword variation pages for long-tail content
- Service pages per industry or vertical
- Directory listings from structured data

---

# Activating

SleekRank can be activated on a site by navigating to the `SleekRank` menu item in the WordPress admin dashboard.

Alternatively, it is also possible to activate SleekRank using PHP. This is done by adding the following code constant to your `functions.php` file:

```php
const SLEEKRANK_LICENSE = "YOUR LICENSE KEY";
```

---

# Sitemap

SleekRank automatically adds all generated pages to your WordPress sitemap, ensuring search engines can discover and index them. It supports multiple SEO plugins out of the box.

## Supported SEO Plugins

SleekRank integrates with the following sitemap providers:

- **WordPress Core Sitemaps** — Built-in sitemaps (WordPress 5.5+)
- **Yoast SEO** — via the `wpseo_sitemap` hooks
- **Rank Math** — via Rank Math's sitemap API
- **The SEO Framework** — via TSF sitemap hooks
- **All in One SEO** — via AIOSEO sitemap hooks

SleekRank detects which SEO plugin is active and hooks into the appropriate sitemap system automatically. No configuration is needed.

## How It Works

When your sitemap is requested, SleekRank loops through all active page groups, resolves every valid URL from the data source, and adds each as a sitemap entry. Each entry includes:

- **URL**: The full generated page URL
- **Last Modified**: Based on the data source last modification time
- **Priority**: Inherited from the base page or configurable per group

## Multiple SEO Plugins

If you have more than one SEO plugin active (not recommended but sometimes unavoidable), SleekRank will integrate with all detected plugins to ensure maximum sitemap coverage.

## Verifying Your Sitemap

After setting up page groups, verify that generated URLs appear in your sitemap by visiting your sitemap URL (usually `/sitemap.xml` or `/sitemap_index.xml`). Look for the URLs matching your page group patterns.

---

# Theme Sync

Theme Sync is a feature that enables bidirectional synchronization between JSON files in your theme directory and the SleekRank database. This is useful for managing page group configurations as code.

## How It Works

When Theme Sync is enabled, SleekRank watches for JSON configuration files in a designated directory within your active theme. Changes flow in both directions:

- **Theme → Database**: When you update a JSON file in your theme, the changes are synced to the database on the next page load
- **Database → Theme**: When you update settings in WP Admin, the changes are written back to the theme JSON files

## Configuration Directory

By default, SleekRank looks for configuration files in:

`/your-theme/sleek-rank/`

Each page group can have a corresponding JSON file in this directory.

## Benefits

- **Version Control**: Track page group configurations in Git alongside your theme
- **Deployment**: Push configuration changes through your deployment pipeline
- **Team Collaboration**: Share page group setups across development environments
- **Backup**: Theme files serve as a natural backup of your configurations

## Conflict Resolution

If both the theme file and the database have been modified since the last sync, the most recently modified version takes priority. You can also manually trigger a sync from either direction in the SleekRank settings.

---

# Hooks

SleekRank provides PHP hooks and filters that allow developers to customize and extend its behavior.

## Filters

### sleekRank/data/item

Filter a resolved data item before it is used for replacements. Receives the item data array and page group object.

```php
add_filter('sleekRank/data/item', function ($item, $pageGroup) {
// Modify data before replacements are applied
$item['name'] = strtoupper($item['name']);
return $item;
}, 10, 2);
```
You can also target a specific page group by slug:

```php
add_filter('sleekRank/data/item/city-pages', function ($item) {
// Only applies to the "city-pages" page group
$item['description'] = wp_trim_words($item['description'], 30);
return $item;
});
```
### sleekRank/replacement/value

Filter the value produced by any replacement before it is injected into the HTML.

```php
add_filter('sleekRank/replacement/value', function ($value, $mapping, $data) {
// Modify any replacement value
return $value;
}, 10, 3);
```
You can also filter by replacement type:

```php
add_filter('sleekRank/replacement/value/tag', function ($value, $mapping, $data) {
// Only applies to tag replacements
return $value;
}, 10, 3);
```
### sleekRank/replacements/before

Filter the HTML content before the replacement engine processes it.

```php
add_filter('sleekRank/replacements/before', function ($html, $data, $mappings) {
// Pre-process HTML before replacements
return $html;
}, 10, 3);
```
### sleekRank/replacements/after

Filter the HTML content after all replacements have been applied.

```php
add_filter('sleekRank/replacements/after', function ($html, $data, $mappings) {
// Post-process HTML after all replacements
return $html;
}, 10, 3);
```
### sleekRank/output/before & sleekRank/output/after

Filter the final page output before and after the output buffer is processed.

```php
add_filter('sleekRank/output/after', function ($html) {
// Add a custom banner to all generated pages
$banner = '<div class="generated-page-banner">Auto-generated</div>';
return str_replace('<body', $banner . '<body', $html);
});
```
### sleekRank/themeSync/postTypes

Filter the post types configuration for theme sync.

```php
add_filter('sleekRank/themeSync/postTypes', function ($postTypes) {
// Customize theme sync configuration
return $postTypes;
});
```
## Actions

### sleekRank/data/resolved

Fires after data has been successfully resolved for a page group item.

```php
add_action('sleekRank/data/resolved', function ($data, $pageGroup) {
// Log or track page resolution
error_log("SleekRank resolved: " . $data['slug']);
}, 10, 2);
```
### sleekRank/register/dataSources

Register custom data source types.

```php
add_action('sleekRank/register/dataSources', function ($registry) {
$registry->register('csv', MyCustomCsvDataSource::class);
});
```
### sleekRank/register/replacements

Register custom replacement types.

```php
add_action('sleekRank/register/replacements', function ($engine) {
$engine->register('custom', MyCustomReplacement::class);
});
```
### sleekRank/register/sitemapIntegrations

Register custom sitemap integrations.

```php
add_action('sleekRank/register/sitemapIntegrations', function ($registry) {
$registry->register(MyCustomSitemapIntegration::class);
});
```

---