Pretty URLs at a Glance
Fluid Topics automatically generates an original set of URLs each time an administrator publishes content to a portal. While these URLs are designed to remain unique and robust, they are not user-friendly. Pretty URLs replace original URLs with a more informative URL that gives the user an idea of what the content is about.
Business value
Using the Pretty URL feature offers the following advantages:
- Content managers can create links that remain stable even as documents change over time, thus eliminating the risk of sharing a dead link.
- Users can easily understand and remember a Pretty URL.
- Document and topic URLs become meaningful.
- From an SEO perspective, search engines use Pretty URLs in the same way as canonical (original) URLs.
- Pretty URLs are easy to read in Google Analytics or in any other analytics platform that uses URLs.
Feature overview
It is possible to define a Pretty URL within content or configure one or more templates for Fluid Topics to use to automatically generate a Pretty URL for all or part of document during the publishing process.
When defining templates, it is possible to add metadata requirements so that template A applies to document type A, template B to document type B, and so on.
For example, the Pretty URL generator has created the following URL for the current version of the Fluid Topics User Guide:
Note that the Pretty URL for the latest version of any document does not include a version number. The version number is only used for older versions.
Once defined, the Pretty URL is considered to be the canonical URL and is used everywhere a URL is required.
Since it is considered to be the current/canonical URL, the Pretty URL has to be UNIQUE and link to one and only one topic or document, now and in the future. This is important to consider when creating templates. A Customer Success Manager can help if needed.
Using templates (as opposed to manually defining a Pretty URL within the content) offers greater flexibility. A template can include a document's name, topic's name, version, language, or any other metadata that helps differentiate one piece of content from another.
Fluid Topics launches a reprocess job to apply Pretty URLs as soon as the templates are defined and saved. Since reprocess jobs can be long (depending on content volume), it is more efficient to define all templates at once, rather than one at a time.
Prerequisites
It is necessary to have the ADMIN or KHUB_ADMIN user role to define Pretty URL templates.
Results
Here are a few examples of Pretty URLs and how they were created.
- A screencast about the *Pretty URL- administration interface: https://doc.fluidtopics.com/r/FT/Screencasts/PrettyUrl_UI.
This Pretty URL was created manually in the original source file using the metadata
ft:prettyUrl. - A Technical Note called Empower Metadata with Fluid Topics, and specifically the section about Pretty URLs: https://doc.fluidtopics.com/r/Empower-Metadata-with-Fluid-Topics/Define-metadata/Built-in-metadata/Define-Pretty-URLs. This pretty URL was created by configuring the template {ft:title} at the document level with the metadata requirement FT_version=3.9 and Audience=public. At the topic level, it would be possible to use the template
{document.ft:prettyUrl}/{parents-and-self.ft:title}. - A Technical Note called Upload FTML Content to Fluid Topics, and specifically an older version (3.7) destined for a public audience: https://doc.fluidtopics.com/r/FTML-Connector-Configuration-Guide. This pretty URL was created by configuring the template {FT_Version}_{audience}/{ft:title} at the document level.
Enable and configure the Pretty URLs feature
Example: How we configure our Pretty URLs
This section explains how we define our pretty URL templates, including metadata requirements and template order, in order to meet the following requirements:
- Our customers can easily access the SaaS version of the documentation using stable URLs.
- Multiple audiences can access the version of the documentation destined for them.
- Since we frequently update our documentation as part of our continuous integration and deployment policy, automatic pretty URL generation must remain relatively simple and resilient.
- Since multiple teams publish different types of documentation using several tools, the pretty URL templates should contain consistent portal URLs and include metadata showing the type of document.
- Upgrading to a new major product version must require only two small changes to the metadata requirements.
Context and objectives
For each document in the Fluid Topics documentation corpus, the following metadata allows us to create different variants:
- {ft_version} for the product version (3.8, 3.9, 3.10, etc.).
- {audience} public or other audience (internal, on premises, etc.).
To ensure that the pretty URL of each document remains unique, we use this metadata in our pretty URL templates.
Our primary objective is to provide a stable URL for the current version of the documentation. Other objectives include the following:
- The URL of each document variant for the current Saas version should remain the same when a new product version is released, and the URL should not include the product version.
- The "public" documentation should not have "public" in its URL.
- The "internal" documentation can include information about the audience.
Settings overview
We define Pretty URL templates at the document level as follows:
| N° | Template | Metadata requirement | URL |
|---|---|---|---|
| 1 | {ft:title} | ft_version=3.9 / audience=public | https://doc.fluidtopics.com/r/Fluid-Topics-User-Guide |
| 2 | {audience}/{ft:title} | ft_version=3.9 | https://doc.fluidtopics.com/r/Fluid-Topics-Configuration-and-Administration-Guide |
| 3 | {FT_Version}_{audience}/{ft:title} | https://doc.fluidtopics.com/r/Fluid-Topics-Configuration-and-Administration-Guide |
The URLs for templates 2 and 3 require authentication since the audience is not public.
The pretty URL generator applies the templates in the order listed. If metadata used in the template is not present in the document, or if the metadata requirement is not met, the generator tries to use the next template.
At the topic level, we use only the following template:
| N° | Template | Metadata requirement | URL |
|---|---|---|---|
| 1 | {document.ft:prettyUrl}/{parents-and-self.ft:title} | https://doc.fluidtopics.com/r/Fluid-Topics-User-Guide |
In this template, the first part means that the topic's pretty URL will begin with the document's pretty URL as defined above. The second part is built on the breadcrumb of the document's Table of Contents and the topic's title.
As a result, topic pretty URLs remain unique even when content is modified or when its location within the document changes.
Maintenance
Since Fluid Topics applies the pretty URL templates automatically, the only maintenance required is to change the metadata requirement based on the version metadata when there is new Fluid Topics release.
Here is an example of the maintenance we performed to make Pretty URLs point to 3.10 content instead of 3.9 content when we released the 3.10 product version:
- Publish the updated documentation. The ft_version metadata value is 3.10. The Pretty URLs are processed, and template 3 is used because the metadata requirement associated with templates 1 and 2 ("ft_version = 3.9") is not met.
- Change the metadata requirement (ft_version = 3.10) in templates 1 and 2.
- Reprocess the content so that the new documentation uses the same stable Pretty URLs as the previous documentation.
After reprocessing, https://doc.fluidtopics.com/r/Fluid-Topics-User-Guide is the URL of the 3.10 version of the Fluid Topics User Guide instead of the 3.9 version.