该项目使用Jekyll + github pages搭建个人wiki知识库。该方法的有点是不要借助任何复杂工具编译，就像普通Jekyll博客一样，对md文件进行静态解析，迅速高效！
该Jekyll wiki主题项目地址为：Duter2016_jekyll-rtd-theme
DEMO地址：deepin用户手册及FAQ
1.项目介绍
如果你使用过github pages，那么该jekyll-rtd-theme的使用将十分简单，首先fork，然后设置为github pages，得到访问地址，在浏览器使用就可以了！
编辑wiki也十分简单，直接在网页上编辑就可以了，不需要依赖其他特殊软件就可以搞定。
具体使用方法见如下整理。
2.文档及排版要求
使用说明
该文档支持多层目录，目录名可为中文。每一层目录下建立一个README.md文档（格式要求见下方），在目录下建立你需要的正式文档.md(格式要求见下方)。
（1）README.md文档格式：
文档头部格式必须为：
---
sort: 1
---
# 该级目录的标题
{% include list.liquid all=true %}
source: `{{ page.path }}`
这里你还可以写点你想的该目录分类的介绍。
参数sort: 1为目录或文档的排序顺序。
（2）正式文档格式：
---
sort: 1
---
source: `{{ page.path }}`
# 你写的文档的标题
文档正文。。。。。。。
参数sort: 1为目录或文档的排序顺序，不使用该参数，文档较多时，显示不清楚层次。
（3）插入带 Jekyll 语法的html代码格式：
本来 Markdown 用来插入 HTML 代码是没有问题的，但是 Jekyll 语法内容直接在文中的任何地方都会被转换，所以也只能借助 Jekyll 语法来解决这一问题。比如，原本的变量：
{{ post.date }}
实质上在其左侧插入了{ % raw % }，在其右侧插入了{ % endraw % }。注意，使用时花括号与百分号之间无空格，该段中为不使其转换，添加了空格。如果你有大段代码需要应用，只需要把它们分别加到整个块的两端即可。
3.本项目使用jekyll-rtd-theme
（1）快速部署
remote_theme: rundocs/jekyll-rtd-theme
You can generate with the same files and folders from rundocs/starter-slim
（2）特色
- 简码 (Toasts card(tip, note, warning, danger), mermaid(流程图，时序图，甘特图，类图等))
- 页面插件 (emoji, gist, avatar, mentions)
- 自动生成侧边栏
- 属性列表定义 (Primer/css utilities, Font Awesome 4)
- Service worker (caches)
- SEO (404, robots.txt, sitemap.xml)
- Canonical Link (Open Graph, Twitter Card, Schema data)
（3）可选参数
| name | default value | description |
|---|---|---|
title |
repo name | |
description |
repo description | |
url |
user domain or cname | |
baseurl |
repo name | |
lang |
en |
|
direction |
auto |
ltr or rtl |
highlighter |
rouge |
Cannot be changed |
# folders sort
readme_index:
with_frontmatter: true
meta:
key1: value1
key2: value2
.
.
.
google:
gtag:
adsense:
mathjax: # this will prased to json, default: {}
mermaid:
custom: # mermaid link
initialize: # this will prased to json, default: {}
scss: # also _includes/extra/styles.scss
script: # also _includes/extra/script.js
translate:
# shortcodes
danger:
note:
tip:
warning:
# 404
not_found:
# copyright
revision:
# search
searching:
search:
search_docs:
search_results:
search_results_found: # the "#" in this translate will replaced with results size!
search_results_not_found:
plugins:
- jemoji
- jekyll-avatar
- jekyll-mentions
编后语
做这个Jekyll wiki的灵感来自深度社区的一个用户手册的帖子、 sphinx-rtd-theme 以及 jekyll-rtd-theme。总体，使用还不错，认为完全可以满足个人知识库的wiki需求。
版权声明：本文由 Duter2016 在 2021年01月21日发表。本文采用CC BY-NC-SA 4.0许可协议，非商业转载请注明出处，不得用于商业目的。
文章题目及链接：《使用Jekyll和github pages构建个人wiki知识库》
