XML Site Haritası ve Hreflang — Geliştirici Kılavuzu ve Yönetim Arayüzü
1. Kurulum ve Bağımlılıklar
Section titled “1. Kurulum ve Bağımlılıklar”pnpm add @vicacha-devs/strapi-plugin-sitemap2. Sunucu Yapılandırması (config/plugins.ts)
Section titled “2. Sunucu Yapılandırması (config/plugins.ts)”Strapi v5 projenizin config/plugins.ts dosyasına eklenti yapılandırmasını ekleyin:
export default ({ env }: { env: (key: string, defaultValue?: string) => string }) => ({ "sitemap": { enabled: true, config: { hostname: env("SITEMAP_HOSTNAME", "https://example.org"), includeHreflang: true, }, },});
3. Strapi v5 Yönetim Arayüzü (Admin UI) Turu
Section titled “3. Strapi v5 Yönetim Arayüzü (Admin UI) Turu”Etkinleştirildiğinde eklenti, Strapi Design System v2 bileşenlerini kullanarak çalışma alanını ve ayarlarını yönetim paneline kaydeder:

Yerelleştirilmiş Arayüz Etiketleri (Türkçe)
Section titled “Yerelleştirilmiş Arayüz Etiketleri (Türkçe)”| Çeviri Anahtarı | Arayüz Metni |
|---|---|
plugin.name |
Site Haritası |
plugin.section.item |
Yapılandırma |
settings.title |
Site Haritası (Sitemap) |
settings.subtitle |
XML site haritası ve site haritası dizini ayarları |
settings.showSitemap |
Site Haritasını Göster |
settings.baseUrl.title |
Temel URL |
settings.baseUrl.description |
Tüm site haritası girdileri için kullanılan temel URL’yi girin |
settings.baseUrl.placeholder |
https://ornek.com |
4. İçerik Türü Varlıkları, Konumları ve Şemaları (strapi.documents)
Section titled “4. İçerik Türü Varlıkları, Konumları ve Şemaları (strapi.documents)”Registers two internal Collection Types (plugin::sitemap.sitemap-content-type and plugin::sitemap.sitemap-content-type-single-url) and one Single Type (plugin::sitemap.sitemap-option) with content-manager.visible: false, while introspecting all public api::* and plugin::* Content-Type entities to generate /api/sitemap/sitemap.xml and /api/sitemap/sitemap-{slug}.xml.
Strapi v5 İçinde İçerik Türü Varlıkları Nerede Bulunur?
Section titled “Strapi v5 İçinde İçerik Türü Varlıkları Nerede Bulunur?”- Settings Panel (4 Tabs):
/admin/settings/sitemap(Settings -> Sitemap -> Configuration— organized into General & Sitemap Index, Collection Types, Custom URLs, and Excluded URLs tabs) - Internal Persistence Entities:
plugin::sitemap.sitemap-content-type(strapi_5_sitemap_plugin_content_types),plugin::sitemap.sitemap-content-type-single-url(strapi_5_sitemap_plugin_content_type_single_urls), andplugin::sitemap.sitemap-option(strapi_5_sitemap_plugin_options)
plugin::sitemap.sitemap-content-type — Sitemap Content Type
Section titled “plugin::sitemap.sitemap-content-type — Sitemap Content Type”Per-locale URL pattern, priority, and changefreq mapping for a Strapi Content-Type entity
Kind:
collectionType· DB Table:strapi_5_sitemap_plugin_content_types· Admin Location: Internal (/admin/plugins/sitemap) · Draft & Publish:No· i18n:No
| Alan (Attribute) | Strapi Türü | Zorunlu | Kısıtlamalar / İlişki |
|---|---|---|---|
type |
string |
No | — |
langcode |
string |
No | — |
pattern |
string |
No | — |
priority |
float |
No | — |
frequency |
string |
No | — |
lastModified |
string |
No | — |
thumbnail |
string |
No | — |
populateLinkedModels |
string |
No | — |
plugin::sitemap.sitemap-content-type-single-url — Sitemap Single URL
Section titled “plugin::sitemap.sitemap-content-type-single-url — Sitemap Single URL”Custom static URL entry included alongside dynamic CMS entries in sitemap.xml
Kind:
collectionType· DB Table:strapi_5_sitemap_plugin_content_type_single_urls· Admin Location: Internal (/admin/plugins/sitemap) · Draft & Publish:No· i18n:No
| Alan (Attribute) | Strapi Türü | Zorunlu | Kısıtlamalar / İlişki |
|---|---|---|---|
slug |
string |
No | — |
priority |
float |
No | — |
frequency |
string |
No | — |
plugin::sitemap.sitemap-option — Sitemap Options
Section titled “plugin::sitemap.sitemap-option — Sitemap Options”Global sitemap configuration (baseUrl, excludedUrls, useSitemapIndex, sitemapDefinitions)
Kind:
singleType· DB Table:strapi_5_sitemap_plugin_options· Admin Location: Internal (/admin/plugins/sitemap) · Draft & Publish:No· i18n:No
| Alan (Attribute) | Strapi Türü | Zorunlu | Kısıtlamalar / İlişki |
|---|---|---|---|
baseUrl |
string |
No | — |
excludedUrls |
json |
No | default: [] |
useSitemapIndex |
boolean |
No | default: false |
sitemapDefinitions |
json |
No | default: [] |
Strapi v5 İçerik Yöneticisi (Content Manager) Entegrasyonu (/admin/content-manager)
Section titled “Strapi v5 İçerik Yöneticisi (Content Manager) Entegrasyonu (/admin/content-manager)”İçerik Yöneticisi Kenar Çubuğu Grubu:
Maps All Public Content Manager Collection Types & Single Types
İçerik Yöneticisi Varlıkları ve Bileşenleri
Section titled “İçerik Yöneticisi Varlıkları ve Bileşenleri”plugin::sitemap.sitemap-content-type(Internal URL pattern mapping for Content Manager entities)plugin::sitemap.sitemap-content-type-single-url(Internal custom static URL entries)plugin::sitemap.sitemap-option(Internal global sitemap settings)

Bu Eklenti Neden Content Manager Varlıkları Oluşturur?
Section titled “Bu Eklenti Neden Content Manager Varlıkları Oluşturur?”@vicacha-devs/strapi-plugin-sitemap keeps its 3 configuration schemas (sitemap-content-type, sitemap-content-type-single-url, sitemap-option) hidden from the Content Manager sidebar (content-manager.visible: false) to prevent accidental schema edits, while dynamically reading published documents and i18n localizations from every public Content Manager Collection Type (api::* and plugin::*):
- Automatic Sync with Content Manager Publishing: Whenever an editor publishes, updates, or unpublishes an
Article,Event,Donation Campaign, orResource Publicationin Content Manager,/api/sitemap/sitemap.xmlautomatically reflects itslastmodandxhtml:linkhreflangalternates.
Strapi Content Manager İçinde Nasıl Kullanılır? (Adım Adım)
Section titled “Strapi Content Manager İçinde Nasıl Kullanılır? (Adım Adım)”- Publish Content in Content Manager: Author and publish localized entries in any
api::*orplugin::*collection inside/admin/content-manager. - Map URL Patterns in Sitemap Settings: Open
/admin/settings/sitemap-> Collection Types tab and bind each Content Manager collection UID + locale to its frontend route pattern (e.g.,/[locale]/articles/[slug]). - Configure Sitemap Index, Custom & Excluded URLs: Use the General & Sitemap Index tab (
Use sitemap index with multiple sitemaps+getSitemapBySlug in Users & Permissions → Public → Sitemap), Custom URLs tab, and Excluded URLs tab in/admin/settings/sitemap.
Content Manager ve Eklenti Çalışma Alanı Senkronizasyonu
Section titled “Content Manager ve Eklenti Çalışma Alanı Senkronizasyonu”Content Manager Kullanım Senaryoları ve Editöryal İş Akışları
Section titled “Content Manager Kullanım Senaryoları ve Editöryal İş Akışları”Content Manager Use Case 1 — Auto-Syndicating Published Content Manager Entries to Multilingual XML Sitemaps
Section titled “Content Manager Use Case 1 — Auto-Syndicating Published Content Manager Entries to Multilingual XML Sitemaps”- Amacı ve Neden Kullanıldığı: Ensure every newly published localized Event, Article, or Publication in Content Manager is immediately indexed with
hreflangalternates. - Content Manager İçinde Uygulama Adımları: Publish the entry across
es,en,ar, andtrin/admin/content-managerand verify its<url>block inGET /api/sitemap/sitemap.xml.
5. Uçtan Uca Kullanım Senaryoları ve İş Akışları
Section titled “5. Uçtan Uca Kullanım Senaryoları ve İş Akışları”Use Case 1 — Dynamic Multilingual Entity URL Pattern Mapping & xhtml:link Hreflang
Section titled “Use Case 1 — Dynamic Multilingual Entity URL Pattern Mapping & xhtml:link Hreflang”- What it is for: Map any localized Strapi Content-Type entity (
api::article.article,plugin::events.event,plugin::resources.publication) to dynamic URL patterns with automatichreflangalternates. - How it works: In
/admin/settings/sitemap(Collection Types tab), map a content type +langcodeto a pattern (e.g.,/[locale]/articles/[slug]),priority, andfrequency(plugin::sitemap.sitemap-content-type).

Use Case 2 — Hybrid Static + CMS Sitemap with Custom Single URLs & Excluded Paths
Section titled “Use Case 2 — Hybrid Static + CMS Sitemap with Custom Single URLs & Excluded Paths”- What it is for: Include static frontend routes (
/es,/es/about-us,/en/about-us) alongside dynamic CMS entries in the same XML sitemap while excluding internal paths (/admin,/api,/404). - How it works: Add static route entries in the Custom URLs tab (
plugin::sitemap.sitemap-content-type-single-url) and exclude internal routes in the Excluded URLs tab of/admin/settings/sitemap.

Use Case 3 — Multi-File Sitemap Index (sitemap-{slug}.xml) for Large Sites
Section titled “Use Case 3 — Multi-File Sitemap Index (sitemap-{slug}.xml) for Large Sites”- What it is for: Split large portals into dedicated sub-sitemaps (e.g.,
/api/sitemap/sitemap-pages.xml,/api/sitemap/sitemap-editorial-and-library.xml,/api/sitemap/sitemap-events-and-liturgy.xml) referenced by a master<sitemapindex>. - How it works: Enable Use sitemap index with multiple sitemaps (
useSitemapIndex: true), grantgetSitemapBySluginUsers & Permissions → Public → Sitemap, and definesitemapDefinitionsin the General & Sitemap Index tab of/admin/settings/sitemap(PUT /sitemap/settings).

6. REST API Uç Noktaları (content-api ve admin)
Section titled “6. REST API Uç Noktaları (content-api ve admin)”| Metot | Uç Nokta Yolu | Kapsam | Denetleyici (Handler) | Kimlik Doğrulama |
|---|---|---|---|---|
GET |
/api/sitemap/sitemap.xml |
content-api |
controller.getSitemap |
Bearer JWT |
GET |
/api/sitemap/sitemap-{slug}.xml |
content-api |
controller.getSitemapBySlug |
Bearer JWT |
GET |
/sitemap/settings |
admin |
controller.getSettings |
Bearer JWT |
PUT |
/sitemap/settings |
admin |
controller.updateSettings |
Bearer JWT |
GET |
/sitemap/content-types |
admin |
controller.getContentTypes |
Bearer JWT |
GET |
/sitemap/locales |
admin |
controller.getLocales |
Bearer JWT |
GET |
/sitemap/allowed-fields |
admin |
controller.getAllowedFields |
Bearer JWT |
7. Sunucu Tarafı Programatik Kullanım (strapi.plugin ve strapi.documents)
Section titled “7. Sunucu Tarafı Programatik Kullanım (strapi.plugin ve strapi.documents)”// Registered services on plugin "sitemap": "service", "settings"const pluginService = strapi.plugin("sitemap")?.service("service");
// Querying records via the Strapi v5 Document Service APIconst records = await strapi.documents("plugin::sitemap.sitemap-content-type").findMany({ limit: 25, sort: "createdAt:desc",});8. Sorun Giderme ve Doğrulama
Section titled “8. Sorun Giderme ve Doğrulama”- Yönetim paneli değişiklikleri görünmüyor:
config/plugins.tsdosyasını güncelledikten sonrapnpm strapi buildkomutunu çalıştırın. - Strapi bağımlılık izolasyonu: React bağlam çakışmalarını önlemek için
pnpm-workspace.yamliçindehoistPattern: ["*", "!@strapi/*"]ayarını koruyun. - Sıkı TypeScript kontrolü: Hem
adminhem deserverpaketlerini doğrulamak içinpnpm checkkomutunu çalıştırın.