Customization

WharfDocs is designed to be easily customizable to match your brand and requirements.

#Configuration

The main configuration file is config.php:

<?php

return [
    'site_name' => 'Your Documentation',
    'site_description' => 'Your project documentation',
    'theme' => 'default',
    'default_page' => 'getting-started/introduction',
    'github_repo' => 'https://github.com/user/repo',
    'logo' => '/assets/logo.svg',
    'social_links' => [
        'github' => 'https://github.com/user',
        'twitter' => 'https://twitter.com/user',
    ],
    'features' => [
        'search' => true,
        'dark_mode' => true,
        'edit_link' => true,
        'toc' => true,
    ]
];

#Styling

#CSS Variables

WharfDocs uses CSS custom properties for theming. Edit templates/layout.php to customize colors:

:root {
    --color-primary: #3b82f6;
    --color-primary-dark: #2563eb;
    --color-bg: #ffffff;
    --color-bg-secondary: #f9fafb;
    --color-text: #1f2937;
    --color-text-secondary: #6b7280;
    --color-border: #e5e7eb;
}

#Custom CSS

Add your own styles in assets/css/style.css:

/* Custom brand colors */
:root {
    --color-primary: #ff6b6b;
    --color-primary-dark: #ee5a52;
}

/* Custom navigation styles */
.nav-item {
    font-weight: 600;
    letter-spacing: 0.025em;
}

#Template Customization

The main template is located at templates/layout.php. You can:

#Add Custom Header Elements

<header class="...">
    <!-- Add your logo -->
    <img src="/assets/logo.svg" alt="Logo" class="h-8">

    <!-- Add custom navigation -->
    <nav>
        <a href="/docs">Docs</a>
        <a href="/blog">Blog</a>
    </nav>
</header>

#Customize Footer

Add a footer section before the closing </body> tag:

<footer class="border-t mt-16 py-8">
    <div class="container mx-auto px-4 text-center">
        <p>&copy; 2024 Your Company. All rights reserved.</p>
    </div>
</footer>

#Modify Layout Structure

Change the layout structure to fit your needs:

<!-- Two-column layout without TOC -->
<div class="flex">
    <aside class="sidebar">...</aside>
    <main class="flex-1">...</main>
</div>

<!-- Single column layout -->
<div class="container mx-auto">
    <main>...</main>
</div>

#Adding Custom Features

#Analytics

Add Google Analytics or other tracking:

<!-- In templates/layout.php, before </head> -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'GA_MEASUREMENT_ID');
</script>

#Custom Markdown Extensions

Extend the Markdown parser in src/MarkdownParser.php:

public function parse($markdown)
{
    // Add custom processing
    $markdown = $this->processCustomSyntax($markdown);

    // Continue with normal parsing
    $html = $this->parsedown->text($markdown);

    return ['html' => $html, 'toc' => $toc];
}

private function processCustomSyntax($markdown)
{
    // Example: Convert ::alert:: blocks
    $markdown = preg_replace(
        '/::alert::(.*?)::\/alert::/s',
        '<div class="alert">$1</div>',
        $markdown
    );

    return $markdown;
}

#Custom Navigation

Modify src/NavigationBuilder.php to change how navigation is generated:

private function formatName($name)
{
    // Custom name formatting
    $name = preg_replace('/^\d+\./', '', $name);
    $name = str_replace(['-', '_'], ' ', $name);

    // Add custom transformations
    $name = str_replace('api', 'API', $name);

    return ucwords($name);
}

#Best Practices

1. Keep customizations organized: Use separate CSS files for custom styles
2. Document your changes: Comment your custom code
3. Test thoroughly: Ensure customizations work in light and dark modes
4. Maintain upgradability: Avoid modifying core files when possible
5. Use version control: Track your customizations with Git