Short URLs
Explanation
A short URL is an XWiki URL without its xwiki, bin and view parts: server.com/Sandbox/WebHome instead of server.com/xwiki/bin/view/Sandbox/WebHome. Shortening them changes both the URLs XWiki accepts and the URLs it generates.
The three parts to remove
A default XWiki URL carries three removable parts, each removed by a different mechanism. They are independent, so you can remove one, two or all three.
| Part | Example | What it is | How to remove it |
|---|---|---|---|
| Application name | /xwiki/ | The context path the servlet container gives the XWiki web application. | Deploy XWiki as the Root Web Application |
| Servlet mapping | /bin/ | The path the Action Servlet is mapped to, which tells the container which servlet handles the request. | One of the two approaches below. |
| Action name | /view/ | What to do with the document: view, edit, delete, and so on. | Hide the View Action in URLs |
Every configuration key these pages set is listed on URL Configuration Properties.
Removing the servlet mapping
This is the only part that configuration alone cannot remove. XWiki maps its Action Servlet to /bin/*, /wiki/* (the prefix of path-based subwikis), /testbin/* and /xwiki/*, so a request carrying none of them has to be rewritten into one of them before it reaches the servlet. Two places can do that, which is the choice to make:
- Configure Short URLs with the UrlRewriteFilter, a servlet filter installed inside the XWiki web application. Use it when nothing sits in front of XWiki.
- Configure Short URLs with Apache HTTP Server or Configure Short URLs with Nginx, where the web server rewrites the path before the request reaches the servlet container. Use one of these when the instance is already behind that web server.
What must not reach the Action Servlet
Whatever performs the rewriting has to leave alone the paths XWiki serves by other means, or it breaks static resources, the REST API and file uploads.
| Path | Why it must be excluded |
|---|---|
| resources, skins | Static resource types, which XWiki deliberately lets fall through to the servlet container's default servlet. |
| webjars, tmp | Resource types with their own handlers: web application libraries, and temporary resources such as generated diagrams. |
| rest | The REST API, served by its own servlet. |
| redirect | The web application's welcome file, which sends a URL carrying no page to the home page. |
| bin, wiki, testbin, xwiki | Already mapped to the Action Servlet. |
| asyncrenderer, authenticate, jcaptcha, job | Each is claimed by another resource handler. |
| websocket | The prefix of the WebSocket end-points, which the realtime editing features connect to. |
| robots.txt | Served as a static file when the instance provides one. |
Why a single catch-all mapping is not enough
The obvious shortcut is to map the Action Servlet to /* in web.xml and change nothing else. It does not work: /skins and /resources match that mapping too, and web.xml leaves them unmapped precisely so that the container's default servlet serves them. Excluding them in the rewrite rules, or serving them from the web server in front of XWiki, is what the two approaches above do instead. Mapping the two paths to the container's own default servlet is not a way out either: on Tomcat that servlet takes no parameter for changing the directory it serves from, so you would have to write one of your own.
What you end up with
| URL | Page shown |
|---|---|
| server.com/Sandbox/WebHome | Sandbox.WebHome |
| server.com/Sandbox/ | Sandbox.WebHome |
| server.com/Document | Document.WebHome |
| server.com/ | Main.WebHome |
FAQ
Will my existing URLs stop working?
The /bin/* mapping stays in place in every approach, so the long form keeps resolving. Removing the application name is the exception: once XWiki is deployed at the root context, a bookmark that still carries /xwiki/ no longer resolves, so keep a redirect for it if such bookmarks exist.
Can short URLs be configured from the administration interface?
No. Every change is made in a configuration file of the instance, and the instance has to be restarted for the change to take effect.
Do short URLs work with path-based subwikis?
Yes. The wiki prefix that carries path-based subwikis is excluded from the rewriting, so a subwiki keeps its /wiki/<name>/ prefix.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
