README.md 9.3 KB
Newer Older
1
## CONTENTS OF THIS FILE ##
2 3 4 5 6

 * Introduction
 * Installation
 * Configuration
 * Usage
7
 * Extending the module
8 9 10
 * How Can You Contribute?
 * Maintainers

11
## INTRODUCTION ##
12

gbyte.co's avatar
gbyte.co committed
13
Author and maintainer: Pawel Ginalski (gbyte.co)
14 15
 * Drupal: https://www.drupal.org/u/gbyte.co
 * Personal: https://gbyte.co/
16

17 18
The module generates multilingual XML sitemaps which adhere to Google's new
hreflang standard. Out of the box the sitemaps index most of Drupal's
19
content entity types including:
20 21 22 23 24

 * nodes
 * taxonomy terms
 * menu links
 * users
25 26 27
 * ...

Contributed entity types like commerce products or media entities can be indexed
28
as well. On top of that custom links and view pages can be added to sitemaps.
29 30 31

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

gbyte.co's avatar
gbyte.co committed
32 33 34
The module also provides an API allowing to create any type of sitemap (not
necessary an XML one) holding links to a local or remote source.

35
## INSTALLATION ##
36 37 38 39

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

40
## CONFIGURATION ##
41

42
### PERMISSIONS ###
43 44 45 46

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

47 48
### ENTITIES ###

49 50 51 52 53
Initially only the home page is indexed in the default sitemap variant. To
include content into a sitemap, visit
/admin/config/search/simplesitemap/entities to enable support for entity types
of your choosing. Bundleless entity types can be configured right on that page,
for bundles of entity types visit the bundle's configuration pages, e.g.
54

55 56 57 58
 * /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
 * ...
59

60
When including an entity type or bundle into a sitemap, the priority setting
61
can be set which will set the 'priority' parameter for all entities of that
gbyte.co's avatar
gbyte.co committed
62 63 64
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.
65

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

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

74 75 76 77
Once variants are set up in admin/config/search/simplesitemap/variants, all the
above settings can be configured and overwritten on a per variant basis right
from the UI.

gbyte.co's avatar
gbyte.co committed
78
As the sitemaps are accessible to anonymous users, bear in mind that only links
gbyte.co's avatar
gbyte.co committed
79 80
will be included which are accessible to anonymous users. There are no access
checks for links added through the module's hooks (see below).
81

gbyte.co's avatar
gbyte.co committed
82 83 84 85 86 87 88
### VIEWS ###

To index views, enable the included, optional module Simple XML Sitemap (Views)
(simple_sitemap_views). Simple views as well as views with arguments can be
indexed on the view edit page. For views with arguments, links to all view
variants will be included in the sitemap.

89 90
### CUSTOM LINKS ###

gbyte.co's avatar
gbyte.co committed
91
To include custom links into a sitemap, visit
92 93
/admin/config/search/simplesitemap/custom.

94 95
### SETTINGS ###

96
The settings page can be found under admin/config/search/simplesitemap.
97
Here the module can be configured and the sitemaps can be manually regenerated.
98

99 100 101 102 103
#### VARIANTS ####

It is possible to have several sitemap instances of different sitemap types with
specific links accessible under certain URLs. These sitemap variants can be
configured under admin/config/search/simplesitemap/variants.
104

105 106 107 108 109 110 111 112
#### AUTOMATIC SUBMISSION ####

It is possible to have the module automatically submit specific sitemap
variants to search engines. Google and Bing are preconfigured. This
functionality is available through the included simple_sitemap_engines
submodule. After enabling this module, go to
admin/config/search/simplesitemap/engines/settings to set it up.

113
## USAGE ## 
114

115
The sitemaps are accessible to the whole world under [variant name]/sitemap.xml.
gbyte.co's avatar
gbyte.co committed
116 117
In addition to that, the default sitemap is accessible under /sitemap.xml. To
view the XML source, press ctrl+u.
118

119
If the cron generation is turned on, the sitemaps will be regenerated according
120
to the 'Sitemap generation interval' setting.
121

122 123
A manual generation is possible on admin/config/search/simplesitemap. This is
also the place that shows the overall and variant specific generation status.
124 125

The sitemap can be also generated via drush: Use the command
126 127 128 129 130 131 132 133 134 135 136 137 138
'drush simple-sitemap:generate' ('ssg'), or 'drush simple-sitemap:rebuild-queue'
('ssr').

Generation of hundreds of thousands of links can take time. Each variant gets
published as soon as all of its links have been generated. The previous version
of the sitemap variant is accessible during the generation process.

## EXTENDING THE MODULE ##

### API ###

There are API methods for altering stored inclusion settings, status queries and
programmatic sitemap generation. These include:
139

140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
 * getSetting
 * saveSetting
 * setVariants
 * getSitemap
 * removeSitemap
 * generateSitemap
 * rebuildQueue
 * enableEntityType
 * disableEntityType
 * setBundleSettings
 * getBundleSettings
 * removeBundleSettings
 * setEntityInstanceSettings
 * getEntityInstanceSettings
 * removeEntityInstanceSettings
 * bundleIsIndexed
 * entityTypeIsEnabled
 * addCustomLink
 * getCustomLinks
 * removeCustomLinks
 * getSitemapManager
    * getSitemapVariants
    * addSitemapVariant
    * removeSitemapVariants
 * getQueueWorker
    * deleteQueue
    * rebuildQueue
    * getInitialElementCount
    * getQueuedElementCount
    * getStashedResultCount
    * getProcessedElementCount
    * generationInProgress
172

173 174 175 176 177 178 179 180 181 182 183 184 185 186

These service methods can be chained like so:

```php
$generator = \Drupal::service('simple_sitemap.generator');

$generator
  ->getSitemapManager()
  ->addSitemapVariant('test');
  
$generator
  ->saveSetting('remove_duplicates', TRUE)
  ->enableEntityType('node')
  ->setVariants(['default', 'test'])
gbyte.co's avatar
gbyte.co committed
187
  ->setBundleSettings('node', 'page', ['index' => TRUE, 'priority' => 0.5])
188
  ->removeCustomLinks()
gbyte.co's avatar
gbyte.co committed
189
  ->addCustomLink('/some/view/page', ['priority' => 0.5])
190 191 192
  ->generateSitemap();
```

193 194 195
See https://gbyte.co/projects/simple-xml-sitemap and code documentation in 
Drupal\simple_sitemap\Simplesitemap for further details.

196
### API HOOKS ###
gbyte.co's avatar
gbyte.co committed
197 198

It is possible to hook into link generation by implementing
gbyte.co's avatar
gbyte.co committed
199
`hook_simple_sitemap_links_alter(&$links, $sitemap_variant){}` in a custom module and altering the
gbyte.co's avatar
gbyte.co committed
200 201 202
link array shortly before it is transformed to XML.

Adding arbitrary links is possible through the use of
gbyte.co's avatar
gbyte.co committed
203
`hook_simple_sitemap_arbitrary_links_alter(&$arbitrary_links, $sitemap_variant){}`. There are no
gbyte.co's avatar
gbyte.co committed
204 205 206 207
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
gbyte.co's avatar
gbyte.co committed
208 209
use of `hook_simple_sitemap_attributes_alter(&$attributes, $sitemap_variant){}` and
`hook_simple_sitemap_index_attributes_alter(&$index_attributes, $sitemap_variant){}`.
210 211

Altering URL generators is possible through
gbyte.co's avatar
gbyte.co committed
212
the use of `hook_simple_sitemap_url_generators_alter(&$url_generators){}`.
gbyte.co's avatar
gbyte.co committed
213

214
Altering sitemap generators is possible through
gbyte.co's avatar
gbyte.co committed
215
the use of `hook_simple_sitemap_sitemap_generators_alter(&$sitemap_generators){}`.
216

217
Altering sitemap types is possible through
gbyte.co's avatar
gbyte.co committed
218
the use of `hook_simple_sitemap_sitemap_types_alter(&$sitemap_types){}`.
219 220 221 222 223

### WRITING PLUGINS ###

There are three types of plugins that allow to create any type of sitemap. See
the generator plugins included in this module and check the API docs
gbyte.co's avatar
gbyte.co committed
224 225 226
(https://www.drupal.org/docs/8/api/plugin-api/plugin-api-overview) to learn how
to implement plugins.

227
#### SITEMAP TYPE PLUGINS ####
gbyte.co's avatar
gbyte.co committed
228

229 230 231
This plugin defines a sitemap type. A sitemap type consists of a sitemap
generator and several URL generators. This plugin is very simple, as it
only requires some class annotation to define which sitemap/URL plugins to use.
gbyte.co's avatar
gbyte.co committed
232

233
#### SITEMAP GENERATOR PLUGINS ####
gbyte.co's avatar
gbyte.co committed
234

235 236
This plugin defines how a sitemap type is supposed to look. It handles all
aspects of the sitemap except its links/URLs.
gbyte.co's avatar
gbyte.co committed
237

238
#### URL GENERATOR PLUGINS ####
gbyte.co's avatar
gbyte.co committed
239

240
This plugin defines a way of generating URLs for one or more sitemap types.
gbyte.co's avatar
gbyte.co committed
241

242 243 244 245 246 247 248
Note:
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.

249 250
See https://gbyte.co/projects/simple-xml-sitemap for further details.

251
## HOW CAN YOU CONTRIBUTE? ##
252

253
 * Report any bugs, feature or support requests in the issue tracker; if
254
   possible help out by submitting patches.
255 256 257 258 259 260
   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
gbyte.co's avatar
gbyte.co committed
261
   donation will be much appreciated.
262
   https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5AFYRSBLGSC3W
263 264
   
 * Feel free to contact me for paid support: https://gbyte.co/contact
265

266
## MAINTAINERS ##
267 268 269

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