Permalinks
Introduced in v3.0.0
Permalinks are used to modify how Trio generates the destination paths and ultimately the URLs of pages that it generates for your site.
Permalinks can be defined in trio.json as well as in the front matter of individual fragment files.
Though originally intended to provide flexibility as to where you wish to target the generation of your article pages, Trio's permalink implementation is general enough to be used for other use cases as well, such as:
- Hoisting your blog's category pages to the blog's root folder.
- Providing you greater flexibility in how you structure the files in your project's fragment folder, such as grouping your fragment files into easily recognizable and manageable sub folders.
Defining Permalinks In trio.json
Prior to v4.0.0, the destination paths generated for the children of a permalink's target folder were all flattened, meaning they were all set to what was defined for the permalink's destination path. The result of this behaviour is that all files that match a permalink's target folder (either directly or are child folders of the target folder) all have the same destination path. This behaviour severely limited the usefulness of permalinks and didn't support all the imagined use cases for permalinks.
Beginning with v4.0.0, this behaviour has changed, and now the destination paths generated for children of a permalink's target folder are no longer flattened, and now reflect their relative path to the target folder's path.
As an example of v4's new permalink behavior, imagine that our project's source/fragments folder contains subfolder/alpha.md, subfolder/beta.md, and subfolder/gamma.md and our project's trio.json file contains a permalink defined as "subfolder: /". When Trio generates our project, the root folder will contain public/alpha/index.html, public/beta/index.html, and public/gamma/index.html. Notice how Trio now preserves the subpaths of child folders relative to their target folder defined in the permalink.
All fragments that are generated for a collection that is also targeted by a permalink's target folder will share the same permalink.
Permalinks that are defined in trio.json must declare one or more target folders, which Trio interprets as being relative to the root/source/fragments folder.
In addition, each permalink must declare the destination path that Trio should apply as the root path to all the fragments it finds in the target folders as well as their descendant folders. The destination paths of these permalinks are interpreted as being relative to the root/public (or root/release, if generating a release build) folder.
Beginning with v4, the destination paths that Trio generates for children of a permalink's target folder now reflect their relative path to the target folder's path.
Parmalinks are defined in trio.json using targets: destination pairs surrounded by either single or double quotes (' or "), where targets is one or more target folders and where destination is the destination path that Trio should apply.
"permalinks": [
"articles: blog"
]The permalink defined in the above example directs Trio to apply `/blog` as the root path for all the fragments that it finds in the root/source/fragments/articles folder and its descendant folders.
You can also use a single permalink to target multiple folders in the root/source/fragments folder with the same destination path as shown below:
You can target multiple folders with the same destination path by using a comma separated list of target folders.
"permalinks": [
"articles, categories, tags: blog"
]The permalink defined in the above example directs Trio to apply `/blog` as the root path for all the fragments that it finds in the root/source/fragments/articles, the root/source/fragments/categories, and the root/source/fragments/tags folders as well as in all their descendant folders.
Defining A Permalink In Fragment Front Matter.
Permalinks defined in fragment front matter only affect the destination paths and ultimately the URLs that are generated for those particular fragments.
The destination paths are interpreted as being relative to the root/public (or root/release, if generating a release build) folder.
To define a permalink in a fragment's front matter, you include the permalink front matter property and assign it the destination path that Trio will use when it generates the destination path for the fragment.
The summary.md fragment in the following example provides summary information for the year 2019, and is located in the source/fragments/history/2019/ folder along with other fragment files related to that year. Besides the 2019 folder, the history folder also contains numerous other folders for other prior years:
<!--
template: default
title: 2019 Recap
appendToTarget: true
permalink: yearinreview/2019
-->The permalink defined in the above example directs Trio to apply /yearinreview/2019 as the destination path for the fragment.
As the above example also demonstrates, fragment-based permalinks provide you great flexibility over how you organize the fragments in your projects and how they will be hosted on the generated site.
Permalink Precedence
Permalinks defined in fragment front matter always take precedence over those defined in trio.json, which allows you to "fine tune" your site's permalink strategy to fit your specific domain requirements.
See Also
Your Financial Support Of This Project Is Greatly Appreciated
Trio is an open source project and is therefore free of charge to use both for noncommercial and commercial use, but when you use Trio to create a new website, please consider donating a few bucks. It doesn't take very long, the process is secure, and it will allow us to continue to support the community and to maintain and enhance Trio going forward.