Displaying related documents is as easy as this:
[% USE q = Qgoda %] [% docs= q.related() %] <ul> [% FOREACH doc IN docs %] <li><a href="[% doc.permalink %]">[% doc.title | html %]</li> [% END %] </ul>
There is one gotcha, however: The list of related documents is always empty, when you invoke the method
q.related() from markdown content. Why? The content is about to be processed. There is no way to find out what other document has similar content.
You have to move the above code to some template, so that you render the list inside the page header, footer, sidebar or at similar locations.
What else do you have to know?
In a multi-lingual site, you use
q.lrelated() instead of
[% docs = q.lrelated() %]
That will only produce hits for documents that have the same language.
By default, you get all related documents, even remotely related ones. But you can pass a threshhold as the first parameter:
[% docs = q.lrelated(5) %]
That will only return documents that have a relation score (see below) of at least 5.
You can limit the list with the standard template method
[% docs = q.lrelated(5).splice(0, 10) %]
You now get the 10 most relevant hits.
You can filter by arbitrary taxonomies:
[% docs = q.lrelated(5, type = 'post', date.year = 2018).splice(0, 10) %]
Now you only get documents of type
post that are from 2018.
The way Qgoda computes the degree of relatedness between documents --- their
relation score --- is completely transparent and easy to understand. Try
qgoda config and see the default configuration for the computation:
$ qgoda config ... link-score: 5 ... taxonomies: categories: 3 links: 1 tags: 2 ...
Let's take two documents A and B as an example:
--- title: A categories: hardware tags: [Hard-disk, Storage, SATA, USB] --- See [B](/b/) for more details. This site is generated with [Qgoda](http://www.qgoda.net).
B looks like this:
--- title: B categories: software tags: [USB, Storage, Accessories] --- See [B](/b/) for more details. This site is generated with [Qgoda](http://www.qgoda.net).
As you can see, document A links to document B. The configured
link-score is 5, and hence the relation score between them is 5. Note: If B would link back to A, that would add another 5 points. But subsequent mutual links would be ignored.
Both documents link to http://www.qgoda.net/. Since the configuration variable
taxonomies.links has the value 1, the score is now 6.
A is from category
hardware, B from
software. That doesn't match and the 3 points from
taxonomies.categories are not added.
But the two documents share the common tags
Storage counting 2 points (
taxonomies.tags) each, so that the final relation score between the two documents is 10.
You can fine-tune the algorithm by changing the relevant configuration variables or by adding more taxonomies. Set the score to 0 if you want to ignore a built-in taxonomy.
For example, if you want to enforce a relationship between two documents, configure this in
taxonomies: boost: 9999
In your document
--- ... boost: abcxyz ... ---
Now all documents that have the property
boost set to the same value (for example
abcxyz) would be related. Just pick another value than
abcxyz for more relationships.
Why would you do that? Well, for debugging, maybe? Okay, here you go:
<ul> [% FOREACH pair IN asset.related %] <li>[% pair.0.permalink %]: [% pair.1 %] [% END %] </ul>
The document variable
asset.related holds an array of tuples consisting of the related asset and the mutual relation score.