layout | title | subtitle | date | author | header-img | catalog | music-id | music-idfull | tags | ||
---|---|---|---|---|---|---|---|---|---|---|---|
post |
使用Jekyll和github pages构建个人wiki知识库 |
用Jekyll+github pages搭建wiki知识库 |
2021-01-21 |
Duter2016 |
img/post-bg-ios9-web.jpg |
true |
|
该项目使用Jekyll + github pages搭建个人wiki知识库。该方法的有点是不要借助任何复杂工具编译,就像普通Jekyll博客一样,对md文件进行静态解析,迅速高效!
该Jekyll wiki主题项目地址为:Duter2016_jekyll-rtd-theme
DEMO地址:deepin用户手册及FAQ
如果你使用过github pages,那么该jekyll-rtd-theme的使用将十分简单,首先fork,然后设置为github pages,得到访问地址,在浏览器使用就可以了!
编辑wiki也十分简单,直接在网页上编辑就可以了,不需要依赖其他特殊软件就可以搞定。
具体使用方法见如下整理。
该文档支持多层目录,目录名可为中文。每一层目录下建立一个README.md
文档(格式要求见下方),在目录下建立你需要的正式文档.md
(格式要求见下方)。
文档头部格式必须为:
{% raw %}
---
sort: 1
---
# 该级目录的标题
{% include list.liquid all=true %}
source: `{{ page.path }}`
这里你还可以写点你想的该目录分类的介绍。
{% endraw %}
参数sort: 1
为目录或文档的排序顺序。
{% raw %}
---
sort: 1
---
source: `{{ page.path }}`
# 你写的文档的标题
文档正文。。。。。。。
{% endraw %}
参数sort: 1
为目录或文档的排序顺序,不使用该参数,文档较多时,显示不清楚层次。
本来 Markdown 用来插入 HTML 代码是没有问题的,但是 Jekyll 语法内容直接在文中的任何地方都会被转换,所以也只能借助 Jekyll 语法来解决这一问题。比如,原本的变量:
{% raw %}
{{ post.date }}
{% endraw %}
实质上在其左侧插入了{ % raw % },在其右侧插入了{ % endraw % }。注意,使用时花括号与百分号之间无空格,该段中为不使其转换,添加了空格。如果你有大段代码需要应用,只需要把它们分别加到整个块的两端即可。
remote_theme: rundocs/jekyll-rtd-theme
You can generate with the same files and folders from rundocs/starter-slim
- 简码 (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)
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需求。