给hugo添加搜索功能

前言

Hugo 这种静态站点默认没有搜索功能，大概因为没了数据库实现反而不方便。Search for your Hugo Website 列出了一些可选项，要么自己生成索引用开源的工具搜索，要么用第三方搜索服务如 algolia。

其实 algolia 也是运营几年的熟脸，提供的免费方案小网站也够用，但是还是第三方依赖，配置的动作同样还是要做的，不如自己来。

自己来的方案里我选择 Github Gist for Fuse.js integration ，因为它不需要另外引入 Node.js、 Grunt 或 Gulp，而是利用 Hugo 内置的功能在 build 的时候生成索引输出到 JSON，看起来更简单的样子。

输出索引文件

第一步：修改配置文件 Config.toml

添加以下内容：

[outputs]
  home = ["HTML", "RSS", "JSON"]

第二步：创建 layouts/_default/index.json

{{- $.Scratch.Add "index" slice -}}
{{- range .Site.RegularPages -}}
  {{- $.Scratch.Add "index" (dict "title" .Title "tags" .Params.tags "categories" .Params.categories "contents" .Plain "permalink" .Permalink) -}}
{{- end -}}
{{- $.Scratch.Get "index" | jsonify -}}

完成后可以从 /index.json 打开索引文件。

注：layouts/ 目录里保存的是 Hugo 的模板文件。layouts/ 是站点级别的模板， themes/<theme name>/layouts/ 是主题级别的模板，站点级别模板的设置优先于主题级别的模板。

创建搜索页面

第一步：创建 content/search.md

---
title: "Search Results"
sitemap:
  priority : 0.1
layout: "search"
---

根据 URL 规则，Hugo 会生成 /search/index.html 或 /search.html 。但是因为 content/ 里的内容不支持插入 JS ，所以此处的关键是 layout: "search" 指定模板文件，之后在模板文件中实现搜索功能。

第二步：创建 layouts/_default/search.html

<section>
  <div>
    <form action="{{ "search" | absURL }}">
      <input id="search-query" name="s"/>
    </form>
    <div id="search-results">
     <h3>Matching pages</h3>
    </div>
  </div>
</section>
<script id="search-result-template" type="text/x-js-template">
  <div id="summary-${key}">
    <h4><a href="${link}">${title}</a></h4>
    <p>${snippet}</p>
    ${ isset tags }<p>Tags: ${tags}</p>${ end }
    ${ isset categories }<p>Categories: ${categories}</p>${ end }
  </div>
</script>
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/fuse.js/3.2.0/fuse.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/jquery.mark.min.js"></script>
<script src="{{ "js/search.js" | absURL }}"></script>

和原链相比去掉了以下这样的代码：

{{ define "main" }} … {{ end }}

此处的 define 其实更像是 implement，或者说 define 这个 block 内的内容，而前提是你已经定义过这个 block。一般是在 Base Template 里，以下面的格式定义：

{{ block "main" . }} … {{ end }}

这个例子是基于 Hugo Resume Theme，它在 layouts/_default/baseof.html 里定义了 block，而我使用的主题没有，结果就是直接使用原链的代码搜索页面会跳白板。

然后，没有 Base Template 可以引用的结果就是搜索界面比较丑，慢慢美化吧。

我就加个简单搜索功能，结果被迫学习了 Hugo 的模板布局架构，嗯，人间正道是沧桑。

第三步：创建 static/js/search.js

这是具体实现搜索功能的 JS 函数，search.html 中被引用，照抄即可。

summaryInclude=60;
var fuseOptions = {
  shouldSort: true,
  includeMatches: true,
  threshold: 0.0,
  tokenize:true,
  location: 0,
  distance: 100,
  maxPatternLength: 32,
  minMatchCharLength: 1,
  keys: [
    {name:"title",weight:0.8},
    {name:"contents",weight:0.5},
    {name:"tags",weight:0.3},
    {name:"categories",weight:0.3}
  ]
};

var searchQuery = param("s");
if(searchQuery){
  $("#search-query").val(searchQuery);
  executeSearch(searchQuery);
}else {
  $('#search-results').append("<p>Please enter a word or phrase above</p>");
}

function executeSearch(searchQuery){
  $.getJSON( "/index.json", function( data ) {
    var pages = data;
    var fuse = new Fuse(pages, fuseOptions);
    var result = fuse.search(searchQuery);
    console.log({"matches":result});
    if(result.length > 0){
      populateResults(result);
    }else{
      $('#search-results').append("<p>No matches found</p>");
    }
  });
}

function populateResults(result){
  $.each(result,function(key,value){
    var contents= value.item.contents;
    var snippet = "";
    var snippetHighlights=[];
    var tags =[];
    if( fuseOptions.tokenize ){
      snippetHighlights.push(searchQuery);
    }else{
      $.each(value.matches,function(matchKey,mvalue){
        if(mvalue.key == "tags" || mvalue.key == "categories" ){
          snippetHighlights.push(mvalue.value);
        }else if(mvalue.key == "contents"){
          start = mvalue.indices[0][0]-summaryInclude>0?mvalue.indices[0][0]-summaryInclude:0;
          end = mvalue.indices[0][1]+summaryInclude<contents.length?mvalue.indices[0][1]+summaryInclude:contents.length;
          snippet += contents.substring(start,end);
          snippetHighlights.push(mvalue.value.substring(mvalue.indices[0][0],mvalue.indices[0][1]-mvalue.indices[0][0]+1));
        }
      });
    }

    if(snippet.length<1){
      snippet += contents.substring(0,summaryInclude*2);
    }
    //pull template from hugo templarte definition
    var templateDefinition = $('#search-result-template').html();
    //replace values
    var output = render(templateDefinition,{key:key,title:value.item.title,link:value.item.permalink,tags:value.item.tags,categories:value.item.categories,snippet:snippet});
    $('#search-results').append(output);

    $.each(snippetHighlights,function(snipkey,snipvalue){
      $("#summary-"+key).mark(snipvalue);
    });

  });
}

function param(name) {
    return decodeURIComponent((location.search.split(name + '=')[1] || '').split('&')[0]).replace(/\+/g, ' ');
}

function render(templateString, data) {
  var conditionalMatches,conditionalPattern,copy;
  conditionalPattern = /\$\{\s*isset ([a-zA-Z]*) \s*\}(.*)\$\{\s*end\s*}/g;
  //since loop below depends on re.lastInxdex, we use a copy to capture any manipulations whilst inside the loop
  copy = templateString;
  while ((conditionalMatches = conditionalPattern.exec(templateString)) !== null) {
    if(data[conditionalMatches[1]]){
      //valid key, remove conditionals, leave contents.
      copy = copy.replace(conditionalMatches[0],conditionalMatches[2]);
    }else{
      //not valid, remove entire section
      copy = copy.replace(conditionalMatches[0],'');
    }
  }
  templateString = copy;
  //now any conditionals removed we can do simple substitution
  var key, find, re;
  for (key in data) {
    find = '\\$\\{\\s*' + key + '\\s*\\}';
    re = new RegExp(find, 'g');
    templateString = templateString.replace(re, data[key]);
  }
  return templateString;
}

注：Hugo 的 static/ 目录存放需要应用的图片、CSS、JS 文件，build 时会直接生成于站点根目录。

后记

配置完成发现中文搜索有问题（中文分词问题，不奇怪），之后再慢慢研究吧。

这个例子使用的是 Fuse.js，但按照这个结构替换为其它 JS 库（Lunr.js …）也是可以的

参考链接

1. 为 Hugo 添加搜索功能
2. Hugo 集成 Algolia 搜索