Debian Codegraph @

docs/ref/contrib/sitemaps.txt

raw
1 =====================
2 The sitemap framework
3 =====================
4
5 .. module:: django.contrib.sitemaps
6 :synopsis: A framework for generating Google sitemap XML files.
7
8 Django comes with a high-level sitemap-generating framework to create sitemap_
9 XML files.
10
11 .. _sitemap: https://www.sitemaps.org/
12
13 Overview
14 ========
15
16 A sitemap is an XML file on your website that tells search-engine indexers how
17 frequently your pages change and how "important" certain pages are in relation
18 to other pages on your site. This information helps search engines index your
19 site.
20
21 The Django sitemap framework automates the creation of this XML file by letting
22 you express this information in Python code.
23
24 It works much like Django's :doc:`syndication framework
25 </ref/contrib/syndication>`. To create a sitemap, write a
26 :class:`~django.contrib.sitemaps.Sitemap` class and point to it in your
27 :doc:`URLconf </topics/http/urls>`.
28
29 Installation
30 ============
31
32 To install the sitemap app, follow these steps:
33
34 #. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS` setting.
35
36 #. Make sure your :setting:`TEMPLATES` setting contains a ``DjangoTemplates``
37 backend whose ``APP_DIRS`` options is set to ``True``. It's in there by
38 default, so you'll only need to change this if you've changed that setting.
39
40 #. Make sure you've installed the :mod:`sites framework<django.contrib.sites>`.
41
42 (Note: The sitemap application doesn't install any database tables. The only
43 reason it needs to go into :setting:`INSTALLED_APPS` is so that the
44 :func:`~django.template.loaders.app_directories.Loader` template
45 loader can find the default templates.)
46
47 Initialization
48 ==============
49
50 .. function:: views.sitemap(request, sitemaps, section=None, template_name='sitemap.xml', content_type='application/xml')
51
52 To activate sitemap generation on your Django site, add this line to your
53 :doc:`URLconf </topics/http/urls>`::
54
55 from django.contrib.sitemaps.views import sitemap
56
57 path(
58 "sitemap.xml",
59 sitemap,
60 {"sitemaps": sitemaps},
61 name="django.contrib.sitemaps.views.sitemap",
62 )
63
64 This tells Django to build a sitemap when a client accesses :file:`/sitemap.xml`.
65
66 The name of the sitemap file is not important, but the location is. Search
67 engines will only index links in your sitemap for the current URL level and
68 below. For instance, if :file:`sitemap.xml` lives in your root directory, it may
69 reference any URL in your site. However, if your sitemap lives at
70 :file:`/content/sitemap.xml`, it may only reference URLs that begin with
71 :file:`/content/`.
72
73 The sitemap view takes an extra, required argument: ``{'sitemaps': sitemaps}``.
74 ``sitemaps`` should be a dictionary that maps a short section label (e.g.,
75 ``blog`` or ``news``) to its :class:`~django.contrib.sitemaps.Sitemap` class
76 (e.g., ``BlogSitemap`` or ``NewsSitemap``). It may also map to an *instance* of
77 a :class:`~django.contrib.sitemaps.Sitemap` class (e.g.,
78 ``BlogSitemap(some_var)``).
79
80 ``Sitemap`` classes
81 ===================
82
83 A :class:`~django.contrib.sitemaps.Sitemap` class is a Python class that
84 represents a "section" of entries in your sitemap. For example, one
85 :class:`~django.contrib.sitemaps.Sitemap` class could represent all the entries
86 of your blog, while another could represent all of the events in your events
87 calendar.
88
89 In the simplest case, all these sections get lumped together into one
90 :file:`sitemap.xml`, but it's also possible to use the framework to generate a
91 sitemap index that references individual sitemap files, one per section. (See
92 `Creating a sitemap index`_ below.)
93
94 :class:`~django.contrib.sitemaps.Sitemap` classes must subclass
95 ``django.contrib.sitemaps.Sitemap``. They can live anywhere in your codebase.
96
97 An example
98 ==========
99
100 Let's assume you have a blog system, with an ``Entry`` model, and you want your
101 sitemap to include all the links to your individual blog entries. Here's how
102 your sitemap class might look::
103
104 from django.contrib.sitemaps import Sitemap
105 from blog.models import Entry
106
107
108 class BlogSitemap(Sitemap):
109 changefreq = "never"
110 priority = 0.5
111
112 def items(self):
113 return Entry.objects.filter(is_draft=False)
114
115 def lastmod(self, obj):
116 return obj.pub_date
117
118 Note:
119
120 * :attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` are class
121 attributes corresponding to ``<changefreq>`` and ``<priority>`` elements,
122 respectively. They can be made callable as functions, as
123 :attr:`~Sitemap.lastmod` was in the example.
124 * :attr:`~Sitemap.items()` is a method that returns a :term:`sequence` or
125 ``QuerySet`` of objects. The objects returned will get passed to any callable
126 methods corresponding to a sitemap property (:attr:`~Sitemap.location`,
127 :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and
128 :attr:`~Sitemap.priority`).
129 * :attr:`~Sitemap.lastmod` should return a :class:`~datetime.datetime`.
130 * There is no :attr:`~Sitemap.location` method in this example, but you
131 can provide it in order to specify the URL for your object. By default,
132 :attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object
133 and returns the result.
134
135 ``Sitemap`` class reference
136 ===========================
137
138 .. class:: Sitemap
139
140 A ``Sitemap`` class can define the following methods/attributes:
141
142 .. attribute:: Sitemap.items
143
144 **Required.** A method that returns a :term:`sequence` or ``QuerySet``
145 of objects. The framework doesn't care what *type* of objects they are;
146 all that matters is that these objects get passed to the
147 :attr:`~Sitemap.location()`, :attr:`~Sitemap.lastmod()`,
148 :attr:`~Sitemap.changefreq()` and :attr:`~Sitemap.priority()` methods.
149
150 .. attribute:: Sitemap.location
151
152 **Optional.** Either a method or attribute.
153
154 If it's a method, it should return the absolute path for a given object
155 as returned by :attr:`~Sitemap.items()`.
156
157 If it's an attribute, its value should be a string representing an
158 absolute path to use for *every* object returned by
159 :attr:`~Sitemap.items()`.
160
161 In both cases, "absolute path" means a URL that doesn't include the
162 protocol or domain. Examples:
163
164 * Good: ``'/foo/bar/'``
165 * Bad: ``'example.com/foo/bar/'``
166 * Bad: ``'https://example.com/foo/bar/'``
167
168 If :attr:`~Sitemap.location` isn't provided, the framework will call
169 the ``get_absolute_url()`` method on each object as returned by
170 :attr:`~Sitemap.items()`.
171
172 To specify a protocol other than ``'http'``, use
173 :attr:`~Sitemap.protocol`.
174
175 .. attribute:: Sitemap.lastmod
176
177 **Optional.** Either a method or attribute.
178
179 If it's a method, it should take one argument -- an object as returned
180 by :attr:`~Sitemap.items()` -- and return that object's last-modified
181 date/time as a :class:`~datetime.datetime`.
182
183 If it's an attribute, its value should be a :class:`~datetime.datetime`
184 representing the last-modified date/time for *every* object returned by
185 :attr:`~Sitemap.items()`.
186
187 If all items in a sitemap have a :attr:`~Sitemap.lastmod`, the sitemap
188 generated by :func:`views.sitemap` will have a ``Last-Modified``
189 header equal to the latest ``lastmod``. You can activate the
190 :class:`~django.middleware.http.ConditionalGetMiddleware` to make
191 Django respond appropriately to requests with an ``If-Modified-Since``
192 header which will prevent sending the sitemap if it hasn't changed.
193
194 .. attribute:: Sitemap.paginator
195
196 **Optional.**
197
198 This property returns a :class:`~django.core.paginator.Paginator` for
199 :attr:`~Sitemap.items()`. If you generate sitemaps in a batch you may
200 want to override this as a cached property in order to avoid multiple
201 ``items()`` calls.
202
203 .. attribute:: Sitemap.changefreq
204
205 **Optional.** Either a method or attribute.
206
207 If it's a method, it should take one argument -- an object as returned
208 by :attr:`~Sitemap.items()` -- and return that object's change
209 frequency as a string.
210
211 If it's an attribute, its value should be a string representing the
212 change frequency of *every* object returned by :attr:`~Sitemap.items()`.
213
214 Possible values for :attr:`~Sitemap.changefreq`, whether you use a
215 method or attribute, are:
216
217 * ``'always'``
218 * ``'hourly'``
219 * ``'daily'``
220 * ``'weekly'``
221 * ``'monthly'``
222 * ``'yearly'``
223 * ``'never'``
224
225 .. attribute:: Sitemap.priority
226
227 **Optional.** Either a method or attribute.
228
229 If it's a method, it should take one argument -- an object as returned
230 by :attr:`~Sitemap.items()` -- and return that object's priority as
231 either a string or float.
232
233 If it's an attribute, its value should be either a string or float
234 representing the priority of *every* object returned by
235 :attr:`~Sitemap.items()`.
236
237 Example values for :attr:`~Sitemap.priority`: ``0.4``, ``1.0``. The
238 default priority of a page is ``0.5``. See the `sitemaps.org
239 documentation`_ for more.
240
241 .. _sitemaps.org documentation: https://www.sitemaps.org/protocol.html#prioritydef
242
243 .. attribute:: Sitemap.protocol
244
245 **Optional.**
246
247 This attribute defines the protocol (``'http'`` or ``'https'``) of the
248 URLs in the sitemap. If it isn't set, the protocol with which the
249 sitemap was requested is used. If the sitemap is built outside the
250 context of a request, the default is ``'https'``.
251
252 .. attribute:: Sitemap.limit
253
254 **Optional.**
255
256 This attribute defines the maximum number of URLs included on each page
257 of the sitemap. Its value should not exceed the default value of
258 ``50000``, which is the upper limit allowed in the `Sitemaps protocol
259 <https://www.sitemaps.org/protocol.html#index>`_.
260
261 .. attribute:: Sitemap.i18n
262
263 **Optional.**
264
265 A boolean attribute that defines if the URLs of this sitemap should
266 be generated using all of your :setting:`LANGUAGES`. The default is
267 ``False``.
268
269 .. attribute:: Sitemap.languages
270
271 **Optional.**
272
273 A :term:`sequence` of :term:`language codes<language code>` to use for
274 generating alternate links when :attr:`~Sitemap.i18n` is enabled.
275 Defaults to :setting:`LANGUAGES`.
276
277 .. attribute:: Sitemap.alternates
278
279 **Optional.**
280
281 A boolean attribute. When used in conjunction with
282 :attr:`~Sitemap.i18n` generated URLs will each have a list of alternate
283 links pointing to other language versions using the `hreflang
284 attribute`_. The default is ``False``.
285
286 .. _hreflang attribute: https://developers.google.com/search/docs/advanced/crawling/localized-versions
287
288 .. attribute:: Sitemap.x_default
289
290 **Optional.**
291
292 A boolean attribute. When ``True`` the alternate links generated by
293 :attr:`~Sitemap.alternates` will contain a ``hreflang="x-default"``
294 fallback entry with a value of :setting:`LANGUAGE_CODE`. The default is
295 ``False``.
296
297 .. method:: Sitemap.get_latest_lastmod()
298
299 **Optional.** A method that returns the latest value returned by
300 :attr:`~Sitemap.lastmod`. This function is used to add the ``lastmod``
301 attribute to :ref:`Sitemap index context
302 variables<sitemap-index-context-variables>`.
303
304 By default :meth:`~Sitemap.get_latest_lastmod` returns:
305
306 * If :attr:`~Sitemap.lastmod` is an attribute:
307 :attr:`~Sitemap.lastmod`.
308 * If :attr:`~Sitemap.lastmod` is a method:
309 The latest ``lastmod`` returned by calling the method with all
310 items returned by :meth:`Sitemap.items`.
311
312 .. method:: Sitemap.get_languages_for_item(item)
313
314 **Optional.** A method that returns the sequence of language codes for
315 which the item is displayed. By default
316 :meth:`~Sitemap.get_languages_for_item` returns
317 :attr:`~Sitemap.languages`.
318
319 Shortcuts
320 =========
321
322 The sitemap framework provides a convenience class for a common case:
323
324 .. class:: GenericSitemap(info_dict, priority=None, changefreq=None, protocol=None)
325
326 The :class:`django.contrib.sitemaps.GenericSitemap` class allows you to
327 create a sitemap by passing it a dictionary which has to contain at least
328 a ``queryset`` entry. This queryset will be used to generate the items
329 of the sitemap. It may also have a ``date_field`` entry that
330 specifies a date field for objects retrieved from the ``queryset``.
331 This will be used for the :attr:`~Sitemap.lastmod` attribute and
332 :meth:`~Sitemap.get_latest_lastmod` methods in the in the
333 generated sitemap.
334
335 The :attr:`~Sitemap.priority`, :attr:`~Sitemap.changefreq`,
336 and :attr:`~Sitemap.protocol` keyword arguments allow specifying these
337 attributes for all URLs.
338
339 Example
340 -------
341
342 Here's an example of a :doc:`URLconf </topics/http/urls>` using
343 :class:`GenericSitemap`::
344
345 from django.contrib.sitemaps import GenericSitemap
346 from django.contrib.sitemaps.views import sitemap
347 from django.urls import path
348 from blog.models import Entry
349
350 info_dict = {
351 "queryset": Entry.objects.all(),
352 "date_field": "pub_date",
353 }
354
355 urlpatterns = [
356 # some generic view using info_dict
357 # ...
358 # the sitemap
359 path(
360 "sitemap.xml",
361 sitemap,
362 {"sitemaps": {"blog": GenericSitemap(info_dict, priority=0.6)}},
363 name="django.contrib.sitemaps.views.sitemap",
364 ),
365 ]
366
367 .. _URLconf: ../url_dispatch/
368
369 Sitemap for static views
370 ========================
371
372 Often you want the search engine crawlers to index views which are neither
373 object detail pages nor flatpages. The solution is to explicitly list URL
374 names for these views in ``items`` and call :func:`~django.urls.reverse` in
375 the ``location`` method of the sitemap. For example::
376
377 # sitemaps.py
378 from django.contrib import sitemaps
379 from django.urls import reverse
380
381
382 class StaticViewSitemap(sitemaps.Sitemap):
383 priority = 0.5
384 changefreq = "daily"
385
386 def items(self):
387 return ["main", "about", "license"]
388
389 def location(self, item):
390 return reverse(item)
391
392
393 # urls.py
394 from django.contrib.sitemaps.views import sitemap
395 from django.urls import path
396
397 from .sitemaps import StaticViewSitemap
398 from . import views
399
400 sitemaps = {
401 "static": StaticViewSitemap,
402 }
403
404 urlpatterns = [
405 path("", views.main, name="main"),
406 path("about/", views.about, name="about"),
407 path("license/", views.license, name="license"),
408 # ...
409 path(
410 "sitemap.xml",
411 sitemap,
412 {"sitemaps": sitemaps},
413 name="django.contrib.sitemaps.views.sitemap",
414 ),
415 ]
416
417
418 Creating a sitemap index
419 ========================
420
421 .. function:: views.index(request, sitemaps, template_name='sitemap_index.xml', content_type='application/xml', sitemap_url_name='django.contrib.sitemaps.views.sitemap')
422
423 The sitemap framework also has the ability to create a sitemap index that
424 references individual sitemap files, one per each section defined in your
425 ``sitemaps`` dictionary. The only differences in usage are:
426
427 * You use two views in your URLconf: :func:`django.contrib.sitemaps.views.index`
428 and :func:`django.contrib.sitemaps.views.sitemap`.
429 * The :func:`django.contrib.sitemaps.views.sitemap` view should take a
430 ``section`` keyword argument.
431
432 Here's what the relevant URLconf lines would look like for the example above::
433
434 from django.contrib.sitemaps import views
435
436 urlpatterns = [
437 path(
438 "sitemap.xml",
439 views.index,
440 {"sitemaps": sitemaps},
441 name="django.contrib.sitemaps.views.index",
442 ),
443 path(
444 "sitemap-<section>.xml",
445 views.sitemap,
446 {"sitemaps": sitemaps},
447 name="django.contrib.sitemaps.views.sitemap",
448 ),
449 ]
450
451 This will automatically generate a :file:`sitemap.xml` file that references
452 both :file:`sitemap-flatpages.xml` and :file:`sitemap-blog.xml`. The
453 :class:`~django.contrib.sitemaps.Sitemap` classes and the ``sitemaps``
454 dict don't change at all.
455
456 If all sitemaps have a ``lastmod`` returned by
457 :meth:`Sitemap.get_latest_lastmod` the sitemap index will have a
458 ``Last-Modified`` header equal to the latest ``lastmod``.
459
460 You should create an index file if one of your sitemaps has more than 50,000
461 URLs. In this case, Django will automatically paginate the sitemap, and the
462 index will reflect that.
463
464 If you're not using the vanilla sitemap view -- for example, if it's wrapped
465 with a caching decorator -- you must name your sitemap view and pass
466 ``sitemap_url_name`` to the index view::
467
468 from django.contrib.sitemaps import views as sitemaps_views
469 from django.views.decorators.cache import cache_page
470
471 urlpatterns = [
472 path(
473 "sitemap.xml",
474 cache_page(86400)(sitemaps_views.index),
475 {"sitemaps": sitemaps, "sitemap_url_name": "sitemaps"},
476 ),
477 path(
478 "sitemap-<section>.xml",
479 cache_page(86400)(sitemaps_views.sitemap),
480 {"sitemaps": sitemaps},
481 name="sitemaps",
482 ),
483 ]
484
485 Template customization
486 ======================
487
488 If you wish to use a different template for each sitemap or sitemap index
489 available on your site, you may specify it by passing a ``template_name``
490 parameter to the ``sitemap`` and ``index`` views via the URLconf::
491
492 from django.contrib.sitemaps import views
493
494 urlpatterns = [
495 path(
496 "custom-sitemap.xml",
497 views.index,
498 {"sitemaps": sitemaps, "template_name": "custom_sitemap.html"},
499 name="django.contrib.sitemaps.views.index",
500 ),
501 path(
502 "custom-sitemap-<section>.xml",
503 views.sitemap,
504 {"sitemaps": sitemaps, "template_name": "custom_sitemap.html"},
505 name="django.contrib.sitemaps.views.sitemap",
506 ),
507 ]
508
509
510 These views return :class:`~django.template.response.TemplateResponse`
511 instances which allow you to easily customize the response data before
512 rendering. For more details, see the :doc:`TemplateResponse documentation
513 </ref/template-response>`.
514
515 Context variables
516 -----------------
517
518 When customizing the templates for the
519 :func:`~django.contrib.sitemaps.views.index` and
520 :func:`~django.contrib.sitemaps.views.sitemap` views, you can rely on the
521 following context variables.
522
523 .. _sitemap-index-context-variables:
524
525 Index
526 -----
527
528 The variable ``sitemaps`` is a list of objects containing the ``location`` and
529 ``lastmod`` attribute for each of the sitemaps. Each URL exposes the following
530 attributes:
531
532 - ``location``: The location (url & page) of the sitemap.
533 - ``lastmod``: Populated by the :meth:`~Sitemap.get_latest_lastmod`
534 method for each sitemap.
535
536 Sitemap
537 -------
538
539 The variable ``urlset`` is a list of URLs that should appear in the
540 sitemap. Each URL exposes attributes as defined in the
541 :class:`~django.contrib.sitemaps.Sitemap` class:
542
543 - ``alternates``
544 - ``changefreq``
545 - ``item``
546 - ``lastmod``
547 - ``location``
548 - ``priority``
549
550 The ``alternates`` attribute is available when :attr:`~Sitemap.i18n` and
551 :attr:`~Sitemap.alternates` are enabled. It is a list of other language
552 versions, including the optional :attr:`~Sitemap.x_default` fallback, for each
553 URL. Each alternate is a dictionary with ``location`` and ``lang_code`` keys.
554
555 The ``item`` attribute has been added for each URL to allow more flexible
556 customization of the templates, such as `Google news sitemaps`_. Assuming
557 Sitemap's :attr:`~Sitemap.items()` would return a list of items with
558 ``publication_data`` and a ``tags`` field something like this would
559 generate a Google News compatible sitemap:
560
561 .. code-block:: xml+django
562
563 <?xml version="1.0" encoding="UTF-8"?>
564 <urlset
565 xmlns="https://www.sitemaps.org/schemas/sitemap/0.9"
566 xmlns:news="https://www.google.com/schemas/sitemap-news/0.9">
567 {% spaceless %}
568 {% for url in urlset %}
569 <url>
570 <loc>{{ url.location }}</loc>
571 {% if url.lastmod %}<lastmod>{{ url.lastmod|date:"Y-m-d" }}</lastmod>{% endif %}
572 {% if url.changefreq %}<changefreq>{{ url.changefreq }}</changefreq>{% endif %}
573 {% if url.priority %}<priority>{{ url.priority }}</priority>{% endif %}
574 <news:news>
575 {% if url.item.publication_date %}<news:publication_date>{{ url.item.publication_date|date:"Y-m-d" }}</news:publication_date>{% endif %}
576 {% if url.item.tags %}<news:keywords>{{ url.item.tags }}</news:keywords>{% endif %}
577 </news:news>
578 </url>
579 {% endfor %}
580 {% endspaceless %}
581 </urlset>
582
583 .. _`Google news sitemaps`: https://support.google.com/news/publisher-center/answer/9606710