teedoc 其它插件

teedoc-plugin-markdown-parser: 默认 markdown 解析插件

site_config.json中配置插件

    "plugins": {
        "teedoc-plugin-markdown-parser":{
            "from": "pypi",
            "config": {
                "toc_depth": 3
            }
        }
    }
  • toc_depth: 文章目录(右边栏)的深度, 默认 3, 代表到h3markdown 中的### 三级标题

teedoc-plugin-jupyter-notebook-parser: jupyter notebook 解析插件

site_config.json中配置插件

    "plugins": {
        "teedoc-plugin-jupyter-notebook-parser":{
            "from": "pypi",
            "config": {
            }
        }
    }

teedoc-plugin-search: 网站搜索插件

让网站和文档支持搜索功能,支持所搜当前文档和全站搜索

要使用,在site_config.json中的plugins关键词中添加:

"plugins": {
    "teedoc-plugin-search":{
        "from": "pypi",
        "config": {
            "search_hint": "Search",
            "env": {
                "main_color": "#4caf7d",
                "main_color_dark": "#1b4c33",
                "hint_shadow_color": "rgba(76, 175, 125, 0.38)"
            }
        }
    }
}

不同文档的提示内容可以在对应的文档config.json中配置,以方便做多语言支持(国际化/i18n), 当然,插件默认支持了中文``英文日文, 翻译在这里, 当默认找不到会使用英文, 手动设置下面这边变量会覆盖插件自带的翻译

支持的配置如下:

"teedoc-plugin-search":{
    "config": {
        "search_hint": "搜索",
        "input_hint": "输入关键词,多关键词空格隔开",
        "loading_hint": "正在加载,请稍候。。。",
        "download_err_hint": "下载文件失败,请刷新重试或检查网络",
        "other_docs_result_hint": "来自其它文档的结果",
        "curr_doc_result_hint": "当前文档搜索结果"
    }
}
  • search_hint: 搜索框(按钮)的提示信息, 默认Search
  • input_hint: 搜索页面搜索框输入提示信息, 默认Keywords separated by space
  • loading_hint: 加载搜索所需的文件提示,默认Loading, wait please ...
  • download_err_hint: 下载搜索所需的文件失败提示,需要用户刷新浏览器重试或者网络环境无法下载文件, 默认Download error, please check network and refresh again
  • other_docs_result_hint: 搜索结果提示,其它文档中的搜索结果, 默认Result from other docs
  • curr_doc_result_hint: 搜索结果提示,当前浏览的文档中的搜索结果, 默认Result from current doc
  • env: 替换部分颜色, 包括
    • main_color: 主颜色, 默认"#4caf7d"
    • main_color_dark: 黑色主题主颜色, 默认"#1b4c33"
    • hint_shadow_color: 阴影颜色,默认rgba(76, 175, 125, 0.38)

teedoc-plugin-baidu-tongji: 百度统计

在每个页面添加百度统计的代码,将访问信息发送到百度,就可以在后台看到访问统计信息了

在百度统计注册登录后,在管理页面添加网站,然后会有一个代码获取页面,里面会有如下的代码

<script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?90c693aa2************c14a50bb49";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
</script>

这里有一串密钥90c693aa2************c14a50bb49,将这一串密钥复制,然后在site_config.json中的plugins关键词中添加:

"plugins": {
    "teedoc-plugin-baidu-tongji":{
        "from": "pypi",
        "config": {
            "code": "这里填访问密钥"
        }
    }
}

部署好网站后,就可以在百度统计后台实时访客页面看到访问信息了

teedoc-plugin-comments-gitalk: gitalk 评论插件

gitalk 是一个基于 github issue问答系统的一个评论工具, 使用 gitalk,无需自建服务器,只需要注册一个github账号, 所有的数据会放在github的一个仓库的issue上。

如果你遇到了问题, 这里也许有你要的答案

要使用, 需要在site_config文件中添加插件

    "teedoc-plugin-comments-gitalk": {
        "from": "pypi",
        "config": {
            "contrainer": "comments-container",
            "env": {
                "clientID": "********",
                "clientSecret": "********",
                "repo": "repo name",
                "owner": "orgnization name or user name",
                "admin": ["user names have write access"],
                "main_color": "#4caf7d",
                "second_color": "#0a7d43"
            },
        }
    }
  • contrainer: 容纳评论的容器标签id,默认是comments-container, 在teedoc-plugin-theme-default插件里面文档页面和博客页面包含了这个标签
  • env: gitalk js 插件的配置项, 更多的参数看这里
    • clientIDclientSecret: 需要在github application 中新建一个应用,可以得到IDSecret
    • repoowner: 就是仓库名和拥有者,比如这里用github.com/teedoc/teedoc.github.io这个仓库的issue作为评论系统,就填teedoc.github.ioteedoc
    • admin: 就是拥有这个仓库写入权限的用户名
    • main_color: 评论主要外观颜色, 可以不设置
    • second_color: 评论次要外观颜色, 可以不设置

每个页面开启评论需要管理员登录gitalk后访问页面,gitalk会自动创建 issue,并且添加标签Gitalk和标签url路径,(路径字符有50个字符的长度限制)。 当然,也有批量创建的方法,这里就不介绍了,可以自行摸索。 已经更新成任何人都可以创建 Issue 了

也可以先手动创建 issue 并且指定issue的标签Gitalk(首字母大写),再添加另一个标签页面的 url 路径或者自定义id(标签是自定义id则需要在使用这个 issue 的页面设置页面 id

env参数除了在site_config设置, 也可在文章的metadata中设置,在设置前面加一个gitalk-前缀, 比如要设置gitalk生成的issuetitle,就可以设置gitalk-title。以下是几个例子:

  • 如果你手动创建了一个 issue, 可以为某篇页面指定使用这个 issue, 为文章在 metadata中指定 issue 的 编号即可
---
title: *****
gitalk-number: 2
---
  • 或者先手动创建 issue, 在页面中指定使用这个带特定标签issue,可以看看官方的例子
---
title: *****
id: Demo
---

or

---
title: *****
gitalk-id: Demo
---

teedoc-plugin-assets: assets 资源添加插件

可以通过这个插件向页面自由添加资源, 比如cssjs资源文件

比如已经添加了资源文件的路径映射,并且有/static/css/custom.css/static/css/custom.js两个文件, 需要将其分别添加到页面头部和尾部, 同时还希望在头部添加一个meta标签

site_config.json:

{
    "route": {
            "assets": {
                "/static/": "static",
            },
        },
    "plugins": {
        "teedoc-plugin-assets":{
            "from": "pypi",
            "config": {
                "header_items": [
                    "/static/css/custom.css",
                    "<meta name=\"plugin-assets\" content=\"example meta item\">"
                ],
                "footer_items": [
                    "/static/css/custom.js"
                ],
                "env":{
                    "main_color": "#000000"
                }
            }
        },
    }
}

如果是cssjs文件,可以这样直接写url, 也可以写http开头的链接。

这里env里面的变量会替换到资源文件中, 在资源文件中通过${变量名}来使用

custom.css:

a {
    color: ${main_color}
}

teedoc-plugin-google-translate: Google 页面翻译插件

功能和 Chrome 的鼠标右键翻译此页面 功能一样

翻译前:

google translate

翻译后:

google translate

"config": {
    "lang": "auto",
    "doc_types": ["page", "doc", "blog"],
    "domain": "/"
}
  • lang: 需要被翻译的页面的语言, 默认建议不要设置, 或者设置为文档的locale一致, 比如localezh_CN,则这个可以设置为zh-CN
  • doc_types: 要展示在那些类型的文档页面中,["page", "doc", "blog"] 中的 0 个 到 3 个,
  • domain: 从哪个网址下载google translate的源码,默认是"/", 代表从本网站下载,也可以设置成 translate.google.com 或者 translate.google.cn

    主要是考虑到中国地区不开代理无法下载请求的某些文件,实际还是要请求translate.googleapis.com的, 在制作插件时发现就算设置成translate.google.cn,有个js文件请求了google.com的域名下的一个cleardot.gif文件,导致网络请求卡住很久直到超时才能加载翻译,所以把那个js文件(element_main.js)修改并放到了本地,这样就可以很快地访问了。 但是这样也有风险,由于代码和 Google服务器的代码分离了,万一哪天Google更新了代码,我们也需要跟着手动更新(虽然大概率不会改),到时欢迎更新修改并提交 PR