Permalinks

WharfDocs automatically generates SEO-friendly permalinks for all documentation pages.

#How Permalinks Work

Permalinks are permanent URLs that point to specific documentation pages. They are:

• Automatically generated from file paths
• SEO-friendly with clean, readable URLs
• Permanent - they don't change unless you rename files
• Canonical - each page has one official URL

#URL Structure

The permalink structure is based on your file organization:

#File to URL Mapping

#Rules

1. Numeric prefixes are removed: 1.getting-started becomes getting-started
2. File extensions are removed: .md is stripped from URLs
3. Index files are simplified: index.md or README.md map to the directory path
4. Lowercase and hyphens: URLs use lowercase letters and hyphens for spaces

#Canonical URLs

Each page includes a canonical URL in the HTML head:

<link rel="canonical" href="https://yoursite.com/getting-started/introduction">

This helps search engines understand the primary URL for each page.

#Generating Permalinks

Permalinks are generated in src/DocumentationEngine.php:

private function generatePermalink($path)
{
    $protocol = isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' 
        ? 'https' 
        : 'http';
    $host = $_SERVER['HTTP_HOST'];
    $basePath = dirname($_SERVER['SCRIPT_NAME']);

    return $protocol . '://' . $host . $basePath . '/' . $path;
}

#Custom Permalinks

You can customize permalink generation by modifying the generatePermalink() method:

#Add Custom Prefix

private function generatePermalink($path)
{
    // Add /docs/ prefix to all URLs
    return $this->getBaseUrl() . '/docs/' . $path;
}

#Use Custom Domain

private function generatePermalink($path)
{
    // Force specific domain
    return 'https://docs.yourdomain.com/' . $path;
}

#Add Trailing Slash

private function generatePermalink($path)
{
    return $this->getBaseUrl() . '/' . $path . '/';
}

#Permalink Best Practices

#1. Keep URLs Short and Descriptive

Good:

• /getting-started/installation
• /api/authentication

Avoid:

• /getting-started-with-the-installation-process
• /section-1/subsection-2/page-3

#2. Use Hyphens, Not Underscores

Good: /user-guide/quick-start

Avoid: /user_guide/quick_start

#3. Maintain Consistency

• Always use lowercase
• Use the same separator (hyphens)
• Follow a logical hierarchy

#4. Plan for the Future

• Choose URLs that won't need to change
• Avoid version numbers in URLs (use separate docs for versions)
• Keep structure flexible for growth

#Redirects

If you need to change a URL, set up redirects to maintain SEO:

#Apache (.htaccess)

# Redirect old URL to new URL
Redirect 301 /old-page /new-page

#Nginx

# In server block
location /old-page {
    return 301 /new-page;
}

#PHP (in index.php)

// Before rendering
$redirects = [
    'old-page' => 'new-page',
    'deprecated/guide' => 'current/guide',
];

if (isset($redirects[$path])) {
    header('Location: /' . $redirects[$path], true, 301);
    exit;
}

#SEO Benefits

Proper permalinks improve SEO by:

1. Descriptive URLs: Search engines understand page content
2. Keyword inclusion: URLs can include relevant keywords
3. User-friendly: Readable URLs are more likely to be shared
4. Stable: Permanent URLs maintain search rankings over time

#Sharing and Linking

Permalinks make it easy to:

• Share specific documentation pages
• Link between documentation pages
• Reference documentation in external content
• Create bookmarks and favorites

Example internal link:

See the [Installation Guide](../getting-started/installation) for setup instructions.

The system automatically resolves relative paths to proper permalinks.

See the Installation Guide for setup instructions.