hexo-related-posts

hexo-related-posts is a plugin for Hexo static site generator that generates related posts list with TF/IDF algorithm.

• Increases time users spend on your website by suggesting related content.
• Supports a few different languages, including English, French, Russian, Italian, Japanese, and many others.
• Allows to define "reserved" words that won't be split during word normalize (e.g. ASP.NET will not be split into ASP and NET).
• Highly customizable. Allows to define weight for every component.

How it works

1. The plugin scans all posts on the website and extracts words for every post.
2. For every word stemmers are applied.
3. After normalizing of the words, they are grouped into a dictionary like word → count for every post.
4. TF/IDF is calculated for every post.
5. Post title, description, keywords, tags, categories are also used to compare the posts.
6. The related_posts property added to every post so you can use it the template and display related posts 🎉.

Requirements

• Hexo: 4.x
• Node 12+

Usage

1. Install the plugin using npm:

$ npm install hexo-related-posts --save-dev

2. Add related_posts to Hexo config file (see details below).
3. The new related_posts property will appear in the page variable.

The example of post layout that generates list of related post:

<% if (page.related_posts && page.related_posts.length > 0) { %>
    <section class="related-posts">
        <h2>Related posts</h2>
        <ul>
        <%
        for (const path of page.related_posts) {
            var posts = site.posts.filter(function(post) {
                return post.path === path;
            });
            if (posts && posts.length > 0) {
                posts.each(function(apost) {
                %>
                <li><a href="<%- url_for(apost.path) %>"><%= apost.title || '(no title)' %></a></li>
                <%
                });
            }
        }
        %>
        </ul>
    </section>
<% } %>

❗️ IMPORTANT NOTE. Before building the website for production you should run hexo clean to re-invalidate all relations between the pages.

Configuration

To configure the plugin add related_posts to Hexo config file. Example:

related_posts:
    enabled: true
    enable_env_name: prod
    filter_threshold: 0.3
    related_count: 3
    weight:
        title: 0.05
        description: 0.05
        keywords: 0.01
        tags: 0.005
        categories: 0.005
        text: 1
    stemmers:
      - en
      - ru
    reserved:
      - asp.net
      - vs.net
      - ado.net
      - .net

| Key | Required | Default value | Description | | --- | --- | --- | --- | | enable | no | true | Flag to disable plugin execution. | | enable_env_name | no | | It's possible to disable plugin execution depending on env variable. For example, if you want to calculate related post only for production build, you can set this parameter to prod. In this case, related post will be generated only if you put prod key during running Hexo, i.e. hexo generate -- --prod | | filter_threshold | no | 0.2 | During related posts calculation some number is going to be calculated. The more value means that the posts more similar. So, if you see that it calculates "unrelated" posts, you can slightly increase this value. | | related_count | no | 5 | Number of posts that will be included into final list of related posts. | | weight | no | | The plugin compares title, description, keywords, tags, categories and text. You can adjust each component value in final estimate by increasing/descreasing corresponding value. | | weight.title | no | 0.05 | Weight for post's title. | | weight.description | no | 0.05 | Weight for post's description. | | weight.keywords | no | 0.01 | Weight for post's keywords. | | weight.tags | no | 0.005 | Weight for post's tags. | | weight.categories | no | 0.005 | Weight for post's categories. | | weight.text | no | 1 | Weight for post's content. | | stemmers | no | [en, ru] | Before final comparision plugin "normailze" the text by clearing symbols from initial text. One of the technique is stemming. This param defines which languages should be used to stem the words. Possible values: nl, en, fr, id, it, jp, no/nb/nn, pt, ru, sv. Check Natural library for more details. | | reserved | no | [] | The array of the reserved words that won't be processed during words normalization. For example, ASP.NET will be splitted into ASP and NET by default. If you want to preserve this, you need to add this to reserved config. |