Sitemap
Introduction
Botble CMS provides a powerful sitemap generation system that automatically creates XML sitemaps for your website. The sitemap functionality is implemented through two packages:
- Sitemap Package (
platform/packages/sitemap
): Provides the core sitemap generation functionality. - Theme Package (
platform/packages/theme
): Includes theSiteMapManager
class that makes it easy to add URLs to your sitemap.
Sitemaps help search engines like Google discover and index your content more efficiently, which can improve your site's visibility in search results.
Basic Usage
Accessing Your Sitemap
By default, your sitemap is available at:
http://your-domain.com/sitemap.xml
This is the main sitemap index that links to other sitemaps for different sections of your website.
Adding URLs to the Sitemap
The most common way to add URLs to your sitemap is by listening for the RenderingSiteMapEvent
event. You can add this code to your theme's functions.php
file or in your plugin's service provider:
use Botble\Theme\Events\RenderingSiteMapEvent;
use Botble\Theme\Facades\SiteMapManager;
\Event::listen(RenderingSiteMapEvent::class, function (RenderingSiteMapEvent $event) {
// Add a single URL
SiteMapManager::add('https://your-domain.com/custom-page', now(), '0.8', 'monthly');
// Add multiple URLs from a collection
$items = YourModel::query()
->wherePublished()
->with('slugable')
->get();
foreach ($items as $item) {
SiteMapManager::add($item->url, $item->updated_at, '0.8', 'weekly');
}
});
Parameters for SiteMapManager::add()
SiteMapManager::add(string $url, ?string $date = null, string $priority = '1.0', string $sequence = 'daily')
- $url: The full URL to add to the sitemap
- $date: The last modified date (can be a string or DateTime object)
- $priority: The priority of this URL relative to other URLs (0.0 to 1.0)
- $sequence: How frequently the page is likely to change (always, hourly, daily, weekly, monthly, yearly, never)
Advanced Usage
Creating Sitemap Sections
Botble CMS organizes sitemaps into sections. Each section is a separate sitemap file that contains related URLs. For example, you might have separate sitemaps for blog posts, pages, products, etc.
To create a new sitemap section, you need to:
- Register the sitemap key
- Create a listener for the
RenderingSiteMapEvent
event
// In your plugin's service provider
use Botble\Theme\Events\ThemeRoutingBeforeEvent;
use Botble\Theme\Facades\SiteMapManager;
$this->app['events']->listen(ThemeRoutingBeforeEvent::class, function () {
// Register sitemap keys
SiteMapManager::registerKey([
'your-custom-section',
// Add more sections if needed
]);
});
Then create a listener for the RenderingSiteMapEvent
event:
use Botble\Theme\Events\RenderingSiteMapEvent;
use Botble\Theme\Facades\SiteMapManager;
class RenderingSiteMapListener
{
public function handle(RenderingSiteMapEvent $event): void
{
// Get the last updated item for the sitemap index
$lastUpdated = YourModel::query()
->wherePublished()
->latest('updated_at')
->value('updated_at');
// If this is the main sitemap index, add your section
if (! $event->key) {
SiteMapManager::addSitemap(SiteMapManager::route('your-custom-section'), $lastUpdated);
return;
}
// If this is your custom section, add the URLs
if ($event->key === 'your-custom-section') {
$items = YourModel::query()
->wherePublished()
->with('slugable')
->get();
foreach ($items as $item) {
SiteMapManager::add($item->url, $item->updated_at, '0.8', 'weekly');
}
}
}
}
Register your listener in your plugin's event service provider:
protected $listen = [
RenderingSiteMapEvent::class => [
RenderingSiteMapListener::class,
],
];
Handling Large Sitemaps with Pagination
For large websites with many URLs, you can use pagination to split your sitemap into multiple files. Botble CMS provides built-in support for paginated sitemaps:
use Botble\Theme\Facades\SiteMapManager;
// Create paginated sitemaps for a section with many items
$totalItems = YourModel::query()->wherePublished()->count();
SiteMapManager::createPaginatedSitemaps('your-section', $totalItems, now());
This will automatically create multiple sitemap files if needed, based on the sitemap_items_per_page
setting.
Monthly Archives for Blog Posts
For blog posts or other time-based content, you can organize your sitemaps by month:
use Botble\Theme\Facades\SiteMapManager;
// Register monthly archives for blog posts
SiteMapManager::registerMonthlyArchives('blog-posts', 2, 5);
This will create sitemap sections for each month, going back 2 years, with up to 5 pages per month.
Sitemap Settings
Botble CMS provides several settings for configuring your sitemaps:
- Enable Sitemap: Enable or disable the sitemap feature
- Sitemap Items Per Page: Maximum number of URLs per sitemap file
- Enable Sitemap Cache: Enable or disable caching of sitemaps
- Sitemap Cache Duration: How long to cache sitemaps (in minutes)
You can access these settings in the admin panel under Settings > General > Sitemap.
Clearing the Sitemap Cache
Sitemap caches are automatically cleared when content is created, updated, or deleted. If you need to manually clear the cache, you can use the following code:
use Botble\Theme\Facades\SiteMapManager;
SiteMapManager::clearCache();
Real-World Examples
Adding Pages to Sitemap
use Botble\Page\Models\Page;
use Botble\Theme\Events\RenderingSiteMapEvent;
use Botble\Theme\Facades\SiteMapManager;
class RenderingSiteMapListener
{
public function handle(RenderingSiteMapEvent $event): void
{
if ($event->key == 'pages') {
$pages = Page::query()
->wherePublished()
->orderByDesc('created_at')
->with('slugable')
->get();
foreach ($pages as $page) {
SiteMapManager::add($page->url, $page->updated_at, '0.8');
}
}
}
}
Adding Blog Categories and Posts
use Botble\Blog\Models\Category;
use Botble\Blog\Models\Post;
use Botble\Theme\Events\RenderingSiteMapEvent;
use Botble\Theme\Facades\SiteMapManager;
class RenderingSiteMapListener
{
public function handle(RenderingSiteMapEvent $event): void
{
if ($key = $event->key) {
switch ($key) {
case 'blog-categories':
$categories = Category::query()
->with('slugable')
->wherePublished()
->get();
foreach ($categories as $category) {
SiteMapManager::add($category->url, $category->updated_at, '0.8');
}
break;
case 'blog-posts':
$posts = Post::query()
->with('slugable')
->wherePublished()
->get();
foreach ($posts as $post) {
SiteMapManager::add($post->url, $post->updated_at, '0.8', 'daily');
}
break;
}
} else {
// This is the main sitemap index
SiteMapManager::addSitemap(SiteMapManager::route('blog-categories'), now());
SiteMapManager::addSitemap(SiteMapManager::route('blog-posts'), now());
}
}
}