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 in order to automatically generate a Pretty URL for all or part of document during the publishing process.
When defining templates, it is possible to add metetadata 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, as in the following examples:
- Fluid Topics version 3.8 Installation Guide for Red Hat (RHEL): https://doc.fluidtopics.com/r/3.8_RHEL/Fluid-Topics-Installation-Guide
- A screencast about Offline mode: https://doc.fluidtopics.com/r/FT/Screencasts/OfflineMode
Once defined, the Pretty URL is considered to be the canonical URL and is used everywhere a URL is required.
Prerequisites
It is necessary to have the ADMIN
or KHUB_ADMIN
user role in order 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/Pretty-URL-Metadata. 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/3.7_public/Upload-FTML-Content-to-Fluid-Topics. 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/premium/Fluid-Topics-Configuration-and-Administration-Guide |
3 | {FT_Version}_{audience}/{ft:title} | https://doc.fluidtopics.com/r/3.8_premium/Fluid-Topics-Configuration-and-Administration-Guide |
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 breadcrump 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.