README.md 6.18 KB
Newer Older
1 2 3 4 5 6 7
CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Installation
 * Configuration
 * Usage
8
 * Extending the module
9 10 11 12 13 14 15
 * How Can You Contribute?
 * Maintainers


INTRODUCTION
------------

Pawel G's avatar
Pawel G committed
16 17
Author and maintainer: Pawel Ginalski (gbyte.co)
https://www.drupal.org/u/gbyte.co
18 19

The module generates a multilingual XML sitemap which adheres to Google's new
20 21
hreflang standard. Out of the box the sitemap is able to index most of Drupal's
content entity types including:
22 23 24 25 26

 * nodes
 * taxonomy terms
 * menu links
 * users
27 28 29 30
 * ...

Contributed entity types like commerce products or media entities can be indexed
as well. On top of that custom links can be added to the sitemap.
31 32 33 34 35

To learn about XML sitemaps, see https://en.wikipedia.org/wiki/Sitemaps.


INSTALLATION
Pawel G's avatar
Pawel G committed
36
------------
37 38 39 40 41 42

See https://www.drupal.org/documentation/install/modules-themes/modules-8
for instructions on how to install or update Drupal modules.


CONFIGURATION
Pawel G's avatar
Pawel G committed
43
-------------
44 45 46 47 48

The module permission 'administer sitemap settings' can be configured under
/admin/people/permissions.

Initially only the home page is indexed in the sitemap. To include content into
49 50 51
the sitemap, visit /admin/config/search/simplesitemap/entities to enable support
for entity types of your choosing. Entity types which feature bundles can then
be configured on a per-bundle basis, e.g.
52

53 54 55 56
 * /admin/structure/types/manage/[content type] for nodes
 * /admin/structure/taxonomy/manage/[taxonomy vocabulary] for taxonomy terms
 * /admin/structure/menu/manage/[menu] for menu items
 * ...
57

58 59
When including an entity type or bundle into the sitemap, the priority setting
can be set which will set the 'priority' parameter for all entities of that
Pawel G's avatar
Pawel G committed
60 61 62
type. Same goes for the 'changefreq' setting. All Images referenced by the
entities can be indexed as well. See https://en.wikipedia.org/wiki/Sitemaps to
learn more about these parameters.
63

64
Inclusion settings of bundles can be overridden on a per-entity
65 66
basis. Just head over to a bundle instance edit form (e.g. node/1/edit) to
override its sitemap settings.
Pawel G's avatar
Pawel G committed
67

68
If you wish for the sitemap to reflect the new configuration instantly, check
69
'Regenerate sitemaps after clicking save'. This setting only appears if a change
70 71 72
in the settings has been detected.

As the sitemap is accessible to anonymous users, bear in mind that only links
Pawel G's avatar
Pawel G committed
73 74
will be included which are accessible to anonymous users. There are no access
checks for links added through the module's hooks (see below).
75 76 77 78 79

To include custom links into the sitemap, visit
/admin/config/search/simplesitemap/custom.

The settings page can be found under admin/config/search/simplesitemap.
80
Here the module can be configured and the sitemaps can be manually regenerated.
81 82 83


USAGE
Pawel G's avatar
Pawel G committed
84
-----
85 86 87

The sitemap is accessible to the whole world under /sitemap.xml.

88
If the cron generation is turned on, the sitemaps will be regenerated according
Pawel G's avatar
Pawel G committed
89 90
to the 'Sitemap generation interval' setting ranging from 'On every cron run' to
'Once a week'.
91 92 93 94 95 96 97

A manual generation is possible on admin/config/search/simplesitemap.

The sitemap can be also generated via drush: Use the command
'drush simple_sitemap-generate'.


Pawel G's avatar
Pawel G committed
98 99 100 101 102
EXTENDING THE MODULE
--------------------

It is possible to hook into link generation by implementing
hook_simple_sitemap_links_alter(&$links){} in a custom module and altering the
Pawel G's avatar
Pawel G committed
103 104 105 106 107 108 109 110 111 112 113
link array shortly before it is transformed to XML.

Adding arbitrary links is possible through the use of
hook_simple_sitemap_arbitrary_links_alter(&$arbitrary_links){}. There are no
checks performed on these links (i.e. if they are internal/valid/accessible)
and parameters like priority/lastmod/changefreq have to be added manually.

Altering sitemap attributes and sitemap index attributes is possible through the
use of hook_simple_sitemap_attributes_alter(&$attributes){} and
hook_simple_sitemap_index_attributes_alter(&$index_attributes){}.

Pawel G's avatar
Pawel G committed
114
Altering URL generator plugins is possible through
115 116
the use of hook_simple_sitemap_url_generators_alter(&$generators){}.

Pawel G's avatar
Pawel G committed
117 118 119 120 121 122 123
In case this module's URL generators do not cover your use case, it is possible
to implement new generator plugins in a custom module. To do it, simply extend
the Drupal\simple_sitemap\Plugin\simple_sitemap\UrlGenerator\UrlGeneratorBase
class. See the generator plugins included in this module and check the API docs
(https://www.drupal.org/docs/8/api/plugin-api/plugin-api-overview) to learn how
to implement plugins.

Pawel G's avatar
Pawel G committed
124 125 126 127 128 129
Overwriting the default EntityUrlGenerator for a single entity type is possible
through the flag "overrides_entity_type" = "[entity_type_to_be_overwritten]" in
the settings array of the new generator plugin's annotation. See how the
EntityUrlGenerator is overwritten by the EntityMenuLinkContentUrlGenerator to
facilitate a different logic for menu links.

Pawel G's avatar
Pawel G committed
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
There are API methods for altering stored inclusion settings, status queries and
programmatic sitemap generation. These include:

 * getSetting()
 * saveSetting()
 * getSitemap()
 * generateSitemap()
 * getGeneratedAgo()
 * enableEntityType()
 * disableEntityType()
 * setBundleSettings()
 * getBundleSettings()
 * setEntityInstanceSettings()
 * getEntityInstanceSettings()
 * removeEntityInstanceSettings()
 * bundleIsIndexed()
 * entityTypeIsEnabled()
 * addCustomLink()
 * getCustomLinks()
 * getCustomLink()
 * removeCustomLink()
 * removeCustomLinks()

These service methods can be chained like so:

\Drupal::service('simple_sitemap.generator')
  ->saveSetting('remove_duplicates', TRUE)
  ->enableEntityType('node')
  ->setBundleSettings('node', 'page', ['index' => TRUE, 'priority' = 0.5])
  ->removeCustomLinks()
  ->addCustomLink('/some/view/page', ['priority' = 0.5])
  ->generateSitemap();
Pawel G's avatar
Pawel G committed
162 163


164 165 166
HOW CAN YOU CONTRIBUTE?
-----------------------

167 168
 * Report any bugs, feature or support requests in the issue tracker, if
   possible help out by submitting patches.
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183
   http://drupal.org/project/issues/simple_sitemap

 * Do you know a non-English language? Help translating the module.
   https://localize.drupal.org/translate/projects/simple_sitemap

 * If you would like to say thanks and support the development of this module, a
   donation is always appreciated.
   https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5AFYRSBLGSC3W


MAINTAINERS
-----------

Current maintainers:
 * Pawel Ginalski (gbyte.co) - https://www.drupal.org/u/gbyte.co