1. 前言

博客搭建并设置好后，还可以给其添加一些额外的功能；而对于Pelican博客，又另外有许多好用的插件可扩展使用。

目前这个博客我添加了以下几种功能：

• 网站Logo和背景大图
• Google Analytics谷歌分析
• Pygment代码语法高亮
• Gitalk留言系统

使用了以下几个插件：

• neighbours # 一个在文章页面用于显示上一篇/下一篇文章的插件
• tipue_search # 一个实现本地站内搜索的插件
• tag_cloud # 标签云插件
• similar posts # 一个用于推荐相关文章的插件
• sitemap # 用于生成站点地图的插件
• pelican-toc # 用于生成文章目录的插件
• random_recd_posts # 这个是自己随手写的一个随机推荐站点内文章的插件。

这几个插件也是见到许多人比较常用的，所以主要介绍一下其安装、设置和使用过程中遇到的问题。（Pelican的插件有挺多的，大家可以在官方插件库这里查看还有哪些切合自己需要。

2. 添加的功能

2.1 网站Logo和背景大图

网站logo和背景图其实是主题模板的特定设置，所以这一项是需要根据主题而定的，如果主题不提供显示logo和背景图的设置，则只能自己修改代码添加。这里我是基于自制的主题，要使用logo的话，需要两个logo文件（默认尺寸165x56），一个是PC桌面浏览器显示的logo，另一个是手机或者窄屏时显示的logo，比如我这里是logo.png和logo_white.png；要使用背景大图的话，需要一张大图片，这里假设为bg.jpg（无尺寸限制）。在静态文件目录中放置好这些文件（比如将它们放在images文件夹）后，在设置文件pelicanconf.py中按如下指定：

SITELOGO = 'images/logo.png'
SITELOGO_WHITE = 'images/logo_white.png'
BG_IMG = 'images/bg.jpg'

即可生效。

2.2 Google Analytics谷歌分析

设置GA的话，需要先去Google Analytics官网，用自己的google帐号登陆后在创建一个绑定这个博客地址的分析帐号，然后在管理帐号的媒体资源设置中查看获取这个帐号对应的跟踪ID（类似UA-123456789-1），在设置文件pelicanconf.py中添加自己的跟踪ID：

GOOGLE_ANALYTICS = 'UA-123456789-1'

一般主题都有analytics.html这样一个模板文件，这个模板文件内容即是各种跟踪代码，模板会自动应用上面的设置。

关于google的跟踪代码，以前使用的是analytics.js，现在最新推荐的是gtag.js，可以通过这两个官方网页了解：GA开发者网站，如何添加gtag.js到网站。

大部分的主题使用的是旧的跟踪代码analytics.js，如果想要更新成gtag.js，则可以编辑analytics.html文件，将其中{% if GOOGLE_ANALYTICS %}到{% endif %}之间的代码换成以下：

{% if GOOGLE_ANALYTICS %}
<script async src="https://www.googletagmanager.com/gtag/js?id={{ GOOGLE_ANALYTICS }}"></script>
<script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', '{{ GOOGLE_ANALYTICS }}');
</script>
{% endif %}

2.3 Pygment代码语法高亮

Pelican支持Pygment代码语法高亮，只要写文章时在代码段前一行写上对应的格式语句，即可自动生效。

一般主题都会带一个跟主题色彩相搭配的Pygment的CSS文件，如果我们对主题的Pygment效果不满意，可以自己编辑其中的CSS规则，也可以到Pyment官网演示站点，找自己喜欢的风格，下载对应的CSS文件来替换主题中的pygment.css文件。

要注意的是，不管是主题自带的还是下载的pygment.css文件，都可以测试一下在文章的代码段中包含特殊符号或者中文字符，看看这些字符会不会带有红框，出现红框的话，则pygment.css文件中应该有

.highlight .err { border: 1px solid #FF0000 } /* Error */

这样一条规则，可以将其删除/注释掉，或者编辑成自己想要的样式。

2.4 Gitalk留言系统

关于留言系统，现在似乎国内能用又不会硬塞些乱七八糟元素的已经很少了。国外的也是处于被墙和可能被墙的状态。 所以选择用Github的Issue系统来当留言系统。

开始时使用的是Gitment，但设置后，在登陆初始化时却一直显示在登陆状态，查看了下Gitment上其他用户发起的此类问题的issue，似乎是Gitment作者的校验服务器没在用了，有人提供自用的服务器地址，却是个公众号强行加自己的网站链接；也有人发了自建服务器的教程，但是是不适用于没有购置服务器而是将博客托管在GithubPage的用户的。所以改用Gitalk，设置基本一样，初始化还更简单些。

这里是Gitalk的官方中文说明页面。

简单些说，就是先申请一个Github应用授权，然后在模板文件中引用一个CSS文件，引用一个JS文件，在article.html页面插入一段显示界面的div代码，插入一段设置留言系统的js代码即可。

申请Github应用授权，在自己的Github账户页面中的设置页面最下边的Developer settings开发者设置的OAuth Apps项新建申请。

申请了一个授权后，比如在我自己的这个主题中，是先在设置文件pelicanconf.py中添加申请到的Github应用授权信息变量：

GITALK_GITHUB_ID = 'elvynlee' # 自己的github用户名
REPO_TO_STORE_COMMENTS = 'elvynlee.github.io' # 储存留言的库，可以用博客这个库，也可以新建一个库
OAUTH_CLIENT_ID = 'c6db63j9jeac7ffc3aac' # 申请到的授权ID
OAUTH_CLIENT_SECRET = '8557b7ea273b274a266779f0afba25c604707493' # 申请到的授权secret码

然后设置留言系统的js代码如下调用变量：

<script>
    var gitalk = new Gitalk({
        clientID: '{{ OAUTH_CLIENT_ID }}',
        clientSecret: '{{ OAUTH_CLIENT_SECRET }}',
        repo: '{{ REPO_TO_STORE_COMMENTS }}',
        owner: '{{ GITALK_GITHUB_ID }}',
        admin: ['{{ GITALK_GITHUB_ID }}',],
        id: '{{ article.locale_date }}-{{ article.slug }}',
        distractionFreeMode: false,
    })
    gitalk.render('gitalk-container')
</script>

而用于显示界面的div层代码则很简单：

{% if GITALK_GITHUB_ID %}
    <div id="gitalk-container" class="mdl-card__supporting-text el-comments">
    </div>
{% endif %}

最后是记得，每发布一篇文章，都要在其下的留言系统中先登陆一下自己的Github账号新建一个issue当这篇文章的留言系统。

3. 添加的插件

常规的添加插件的方法：在Pelican目录下新建一个plugins文件夹，将要使用的插件以文件夹的方式放到这个plugins文件夹下，然后在设置文件pelicanconf.py中，添加：

PLUGIN_PATHS = ['plugins',]
PLUGINS = ['neighbors', 'tipue_search', 'tag_cloud', 'similar_posts', 
'sitemap', 'pelican-toc', 'random_recd_posts']

第一行即指定插件的路径和目录名；第二行即指定所要使用的插件名，这些插件名应该跟插件的文件夹同名。 所以，也可以直接克隆复制Pelican官方的插件库到本地，然后将路径指到这个插件库。

下面针对这几个用到插件主要说一些对比区别和遇到的坑。

3.1 neighbours

neighbours插件添加安装好即可生效，不需要任何额外设置。一般主题模板文件也会包含，简单地调用两个变量实现上一篇文章/下一篇文章的功能。

3.2 tipue_search

注意这里，Tipue Search是一个成熟的jQuery站内搜索插件，而这里tipue_search是一个调用Tipue Search实现本地站内搜索的Pelican插件。

其原理是tipue_search会将整个站点的文章内容序列化后生成一个tipuesearch_content.js内容文件，而Tipue Search可以从这个内容文件中检索我们要搜索的信息。

所以如果主题模板包含有tipue_search插件的模块，则只需下载安装好插件，在插件列表中添加'tipue_search'并且加上应用到哪些模板文件，就可以生效：

PLUGINS = [..., 'tipue_search', ...]

DIRECT_TEMPLATES = ['index', 'tags', 'categories', 'authors', 'archives', 'search']

如果主题中不带tipue_search插件的模块，而我们要安装使用tipue_search插件的话，就需要安装'tipue_search'pelican插件同时，下载Tipue Search的这个jQuery插件的文件，并自己编写相应的页面代码，以下供参考：

Tipue Search依赖jQuery，所以确保我们的base.html页面中有引用jquery文件。

在Tipue Search官网下载其需要的js和css文件，比如我们将这里的文件下载后一起放在tipuesearch文件夹中。

安装添加Pelican插件tipue_search，设置文件中我们添加一个变量TIPUE_SEARCH用于模块判断

PLUGINS = [..., 'tipue_search', ...]
TIPUE_SEARCH = True
DIRECT_TEMPLATES = ['index', 'tags', 'categories', 'authors', 'archives', 'search']

新建一个search.html文件，文件代码为：

{% extends "base.html" %}

{% block extra_css %}
    <link rel="stylesheet" href="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/tipuesearch/tipuesearch.css"/>
{% endblock %}

{% block content %}
    <div id="tipue_search_content">
    </div>
{% endblock content %}

{% block extra_js %}
    <script src="{{ SITEURL }}/tipuesearch_content.js"></script>
    <script src="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/tipuesearch/tipuesearch_set.js"></script>
    <script src="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/tipuesearch/tipuesearch.min.js"></script>
    <script>
    $(document).ready(function() {
        $('#tipue_search_input').tipuesearch({
            'minimumLength': 1,
            'show': 15,
            'showTime': false,
            'showURL': false,
            'wholeWords': false,
        });
    });
    </script>
{% endblock extra_js %}

这个页面代码中，注意的几点是：

• 调用Tipue Search的文件是在继承base.html页面中的extra_css和extra_js两个块中扩展调用的，内容文件也是在这里调用。这样扩展的前提是base.html页面中有这两个块。
• 注意调用本地文件使用的地址变量，这里是以放置在主题文件夹下为例
• 最后一段对Tipue Search的设置代码中，'minimumLength'设为1和'wholeWords'设为false，都是针对中文搜索，这样设置后，我们搜索单个中文字也可以有搜索结果。

最后，在base.html页面中，将搜索框的提交跳转到这个search.html页面，搜索框的代码类似这样：

<form class="" action="/search.html" onsubmit="return validateForm(this.elements['q'].value);"> 
    <input class="" type="text" name="q" id="tipue_search_input">
</form>

最后加一小段js判断代码：

<script>
    function validateForm(query)
    {
        return (query.length > 0);
    }
</script>

这样即完整地添加了tipue_search插件。

以下是几点注意的地方：

• 如果有自己的搜索框界面，记得将Tipue Search的CSS文件中的#tipue_search_input {}的规则注释掉，不然搜索结果页会优先引用它。
• 如果设置都正确了，搜索时却显示nothing found，一是检查生成的tipuesearch_content.js内容文件是否在output根目录下，二是检查对jQuery文件的引用是否在所有js文件引用和js代码块的前面。
• Tipue Search默认的设置对中文搜索是不友好的，需要在设置代码中添加这两项'minimumLength': 1,和'wholeWords': false,才会正常。
• 可以编辑tipuesearch.css方便地自定义修改样式，但布局在js文件中，修改比较复杂。
• 将tipuesearch模块放到其他页面时，记得检验搜索能否出结果。试过将搜索模块单独放在index页面，结果搜索不了。没有细究，最后还是固定放在base页面。

3.3 tag_cloud

tag_cloud默认安装添加后，初始的模块效果是很简单的，所以安装标签云模块更多的工作是编写好看的CSS样式。

tag_cloud的设置有：

TAG_CLOUD_STEPS = 4
TAG_CLOUD_MAX_ITEMS = 100
TAG_CLOUD_SORTING = 'random'
TAG_CLOUD_BADGE = True

这里有一个坑：

比如TAG_CLOUD_STEPS设置为4，然后在编写对应的CSS规则中官方是按tag-1，tag-2，tag-3，tag-4的示例，当我们也设置了好tag-1，tag-2，tag-3，tag-4后，实际使用时随着某个tag的数量增多，会发现代码中无端出来一个tag-0的class，由于我们没有编写tag-0的规则，它会显示成默认的效果。

所以，当发现有这样的问题时，可以通过修改steps让插件重新分配一次，或者最好加上一个tag-0的规则。

3.4 similar posts

similar posts是用于当前文章相关推荐的一个插件，另外可以实现此功能的还有一个related posts。两者的区别是similar posts会计算标签tag的权重来推荐相关文章，更能推荐到关联度高的文章。

插件的安装和使用没有什么要注意的。

3.5 sitemap

sitemap插件用于生成站点地图，可以将生成的sitemap定期提交到搜索引擎的webmaster（Google现在是Google Search Console），让搜索引擎收录网站的文章。

安装添加插件后，再在设置文件pelicanconf.py中添加：

SITEMAP = {
    'format': 'xml',
    'priorities': {
        'articles': 0.5,
        'indexes': 0.5,
        'pages': 0.5
    },
    'changefreqs': {
        'articles': 'weekly',
        'indexes': 'daily',
        'pages': 'weekly'
    }
}

生成的文件为output目录下的sitemap.xml。

3.6 pelican-toc

pelican-toc是生成文章目录的插件。这里也有另一个功能类似的插件extract toc，两者的区别是extract toc是读取pelican从文章生成的目录，pelican-toc则不通过pelican而自己来生成文章目录。貌似区别不大。

目录的CSS样式可以自行编写CSS规则定制。

3.7 random_recd_posts

这是一个自己随手编写的插件，随机获取整个站点的指定篇文章，用于首页的随机推荐模块。

当然，由于是静态站点，所以从访问者角度，是不能浏览页面时刷新一次就变成不同的随机文章的，而只是每次我们重新生成站点发布时它才重新随机生成推荐的文章。

4. 结语

其他的插件，需要用到时再更新补充吧。