Add URL Aliases and Breadcrumbs docs.

docs/user-documentation/breadcrumbs.md

@@ -0,0 +1,32 @@
+# Breadcrumbs
+
+Breadcrumbs are a Drupal concept. They provide a hierarchical path
+of links to "ancestors" of the current content item.
+
+![example of breadcrumbs](../assets/breadcrumbs-example.png)
+
+## Islandora Breadcrumbs
+
+Islandora provides a module, "Islandora Breadcrumbs" (a submodule
+of the Islandora module) that creates breadcrumbs based on the value
+of configured reference fields (by default, `field_member_of`). 
+To use Islandora Breadcrumbs, simply enable
+the module. Islandora breadcrumbs will apply to nodes that have
+the configured Entity Reference fields.
+
+There are a few configuration options for this module, accessible at
+**Manage** > **Configuration** > **Islandora** > **Breadcrumbs 
+Settings** (`/admin/config/islandora/breadcrumbs`). These include:
+
+* Maximum number of ancestor breadcrumbs - an optional feature to 
+stop adding "ancestor" links after a certain number
+* Include the current node in the breadcrumbs?
+* Entity Reference fields to follow - if you're using other fields
+to refer to parents, you can add them here.
+
+![configuration screen](../assets/breadcrumbs-config-screen.png)
+
+## Troubleshooting Breadcrumbs
+
+Breadcrumbs are cached, so if you aren't seeing the results that 
+you expect, try clearing the Drupal cache.

docs/user-documentation/url-aliases.md

@@ -0,0 +1,51 @@
+# URL Aliases
+
+A URL alias is an alternate URL pattern that resolves to a Drupal entity,
+such as a node, media, taxonomy term, or user. For example, you could set
+"/welcome" as an alias for "/node/1". Aliases are part of Drupal Core and
+can be extended by contrib modules. One such module is Pathauto, which 
+enables automatic alias generation based on patterns, and the patterns may
+involve "Tokens" (such as [node:title]). 
+
+This page will attempt to cover the Islandora Starter Site's use of aliases
+and what we consider to be best practices. A full description of creating 
+and managing aliases is out of scope.
+
+
+## Best practices with URL aliases
+
+While every site may choose to set up their aliases differently, we cannot
+prescibe a universal setup.
+
+A common "nice-to-have" is the presence of the slug `/islandora/` in the
+URL which identifies the content as "Islandora". 
+
+A potential "best practice" is that if your site uses persistent identifiers
+such as DOIs or Handles, that those identifiers make up part of the URL alias.
+
+
+## Use of URL aliases in Islandora Starter Site
+
+The Islandora Starter Site includes the Pathauto module, which we consider
+that most sites will want to use in some way. However its default configuration
+should not be interpreted as prescriptive. You are encouraged to use persistent
+identifiers if you have them!
+
+The default Pathauto pattern for Repository Items is `/islandora/[node:title]`
+with the pathauto configuration trimming the alias at 100 characters.
+
+
+## Preserving Legacy URLs
+
+Sites migrating from Islandora Legacy may wish for their objects to still 
+be available through their old URLs, with the pattern `/islandora/object/[PID]`. 
+
+Options for doing this include:
+
+* Populating `field_pid` with the legacy PID, and using Pathauto to create URL
+aliases of the pattern `/islandora/object/[node:field_pid]`. However, you will
+need to set up something for new objects that don't have Legacy PIDs.
+* Use discoverygarden's ["PID Redirect"](https://github.com/discoverygarden/pid_redirect)
+module, which creates "301 Moved Permanently" redirects from legacy URLs to
+the appropriate node, based on `field_pid`. 
+* Manually managing redirects in your webserver. 

mkdocs.yml

@@ -208,8 +208,10 @@ nav:
               # Conceptual and pragmatic, for repository managers.
       - Administering Islandora:
           - 'Access control': 'user-documentation/access-control.md'
+          - 'Breadcrumbs': 'user-documentation/breadcrumbs.md'
           - 'JWT authentication': 'user-documentation/jwt-authentication.md'
           # moved from Developer documentation
+          - 'URL Aliases': 'user-documentation/url-aliases.md'
           - 'Usage statistics': 'user-documentation/usage-stats.md'
           # largely conceptual, repository managers
           - 'Versioning': 'user-documentation/versioning.md'