User:Alice/Kitchen/Breadcrumb navigation
Wikivoyage has a feature to show bread crumb menus under the title of an article to show our logical hierarchy and make navigation easier.
For destination articles, this bread crumb trail will show the countries and regions that a destination belongs to.
For Travel topics, the trail will show related topics and also designate that the article is a travel topic and not a destination article.
Examples
[edit]Europe > Russia > Southern Russia > North Caucasus > Dagestan
Travel topics > Travel activities > Sport > Scuba diving > Diving in Barbados > Diving in Barbados/Cobblers Reef
This can make it easier to navigate the site and find bigger or nearby destinations or related travel topics. This page describes how to add a bread crumb menu to a page.
When to use
[edit]Breadcrumb navigation should be used for all destination articles. It should not be used for itinerary articles, even if they are located within a geographical area.
Use is optional, but encouraged, for travel topics.
To add a menu, you need to specify the next larger area that a place is in. For example, Montreal is in Quebec, and Germany is in Central Europe.
To say that a place is in another place, put the "isPartOf" template at the bottom of the page, with the name of the larger place. So, Montreal's guide has a line saying {{isPartOf|Quebec}}, and Germany's guide has a line {{isPartOf|Central Europe}}.
By convention, this template is placed at the end of the destination article.
- If there are two "IsPartOf" templates, the breadcrumb navigation code only uses the last one.
- You only need to specify the immediately next bigger area. Germany is in Europe, but we don't need to add {{isPartOf|Europe}} to the Germany page, since Central Europe is already marked as being in Europe.
- Interaction with the caching system is poor. If you change the location of a larger entity, the cached pages for its contained entities are not updated. You can purge them using "action=purge" to cache and re-load the page.
- Disambiguators won't be shown unless two parts of the hierarchy have the same ambiguous name (see, for example, Tokyo).
For Travel topics breadcrumbs can be added using the {{PartOfTopic}} template.
Subordinate articles
[edit]Any page within an hierarchy that "IsPartOf" an article is a subordinate page to that article and there should be a link to it in the appropriate section of the article, so the subordinate article can be reached directly from the higher level article. The name of this section will vary depending on the level of the article in the hierarchy. In the geographical hierarchy the section name will be the type of subordinate geographical subdivision, such as Continental section, Country, Region etc.
A similar arrangement should be present in any travel topic using "PartOfTopic" for hierarchical organisation. Details will vary.
Subpages
[edit]Subpages are commonly used for districts of huge cities. In this case the breadcrumb navigation assumes that the subpage lies within the parent page. For instance the article London/Westminster is recognised as a sub-region of London.
A corresponding arrangement can be used in hierarchically organised travel topics.
However if the template is omitted, no RDF will be generated for the isPartOf relationship.
Categories
[edit]The breadcrumb at the top of the page allows you to walk up the trail to larger regions or more inclusive topics. To browse to places in the same region or down the trail to smaller places use the category at the bottom of the page.
The category is the same name as the region places in the isPartOf template. Note if the category does not exist a small link will be created at the bottom of the page to assist in creating the category with the correct content. See Wikivoyage:Region categories.
Troubleshooting
[edit]- If the breadcrumb menu doesn't show up at all,
- Be sure that there is an IsPartOf or PartOfTopic template in the article
- Be sure that there isn't another isIn or IsPartOf or PartOfTopic in the article text (this is occasionally a source of broken breadcrumbs)
- If you've changed the IsPartOf or PartOfTopic setting for an article, or its parent, but the breadcrumb menu still shows the old contents, then likely the cached IsPartOf or PartOfTopic information is incorrect. Fix this by purging the cache. You must do this with every article below the one which changed, down to the current article. Start with articles which are IsPartOf or PartOfTopic to the changed article, and work down to all articles which are IsIn them, and so on. (If you change the IsPartOf relationship of a top-level article, there can be a lot of caches to purge!).
- You can purge the cache by clicking on the History tab of the article, giving the History page and in the browser's location (URL) bar, find the string "action=history", and change it to "action=purge", then push the Enter key, giving a view of the article with no breadcrumb menu; 3) click on the Article tab, giving the article with a correct breadcrumb menu.
- You can also edit the article, and click on the Purge cache link at the bottom of the page.
- If there's only a partial GeoCrumbs trail, (such as "Orange County > Beaches > Some town" instead of "North America > USA > California > Orange County CA > Beaches > Some town"), check the first region listed in the crumb trail to verify that article has the "isPartOf" tag. If Orange County is a disambiguation page, it will have no tags so the trail goes cold. If there's a redirect as an isPartOf target, that redirect (and not just the other page to which it is redirected) must have "isPartOf" to continue the trail.
Under the covers
[edit]The crumbs are generated by mw:Extension:GeoCrumbs.
The breadcrumb navigation code uses the RDF isPartOf relation defined by the IsPartOf template to determine the geographical hierarchy of a destination. The RDF defines the relationship between two places, and the navigation code reads that relationship. An exception to this occurs when using subpages. Subpages are commonly used for districts of huge cities. In this case the template and associated RDF are ignored, and the breadcrumb navigation assumes that the subpage lies within the parent page.
GeoCrumbs are based on a tree structure and presume that each destination or region isPartOf only one parent region. This requires workarounds for places which fall on regional boundaries:
- Russia isPartOf Europe, Russia (Asia) is a redirect to Russia but isPartOf Asia. Siberia isPartOf Russia (Asia).
- Niagara Falls and Kansas City each has two separate articles, with the listings split at the state line.
If there are two or more "isPartOf" tags on an article, the extension ignores all but the last tag. There are no automated tools to verify which places are part of a region; links generated as part of the breadcrumb trail are not displayed by special:whatlinkshere.
The open source code for the extension is available from Wikimedia's git version control system.