This repository has been archived by the owner on Oct 2, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
theme.html
204 lines (166 loc) · 10.8 KB
/
theme.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
<!DOCTYPE html>
<html lang="zh-hans">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no"/>
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta http-equiv="cleartype" content="on">
<link rel="alternate" type="application/atom+xml" title="VeriPress Docs" href="/docs/feed.xml"/>
<!-- Link common CSS and JavaScript files -->
<link href="//cdn.bootcss.com/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet">
<link href="/docs/static/style.css" rel="stylesheet">
<link href="/docs/static/github-markdown-style.css" rel="stylesheet">
<link href="/docs/static/highlight.css" rel="stylesheet">
<link href="/docs/static/bootstrap-theme-cosmo.min.css" rel="stylesheet">
<link rel="shortcut icon" type="image/x-icon" href="/docs/static/favicon.ico">
<title>主题 - VeriPress Docs</title>
</head>
<body>
<div class="section">
<div class="container">
<div class="row">
<div class="col-md-2"></div>
<div class="col-md-8">
<div class="row site-header-row">
<div class="col-md-8 site-header">
<h1><a href="/docs/">VeriPress Docs</a><br>
<small>Documentation of VeriPress.</small>
</h1>
</div>
</div>
<div class="row">
<div class="col-md-12 nav-container">
<ul class="nav nav-tabs">
<li><a href="/docs/">简体中文</a></li>
<li><a href="/docs/en/">English</a></li>
<li><a href="https://github.com/veripress/veripress">GitHub</a></li>
</ul>
</div>
</div>
</div>
<div class="col-md-2"></div>
</div>
<div class="row">
<div class="col-md-2"></div>
<div class="col-md-8">
<div class="panel panel-primary">
<div class="panel-heading"></div>
<div class="panel-body markdown-body">
<article>
<h1>主题</h1>
<hr>
<ul>
<li><a href="#安装官方主题">安装官方主题</a></li>
<li><a href="#安装第三方主题">安装第三方主题</a></li>
<li><a href="#更新和删除主题">更新和删除主题</a></li>
<li><a href="#在已有主题的基础上自定义">在已有主题的基础上自定义</a><ul>
<li><a href="#修改主题模板的某一部分">修改主题模板的某一部分</a></li>
<li><a href="#在文章或页面中使用自定义布局">在文章或页面中使用自定义布局</a></li>
</ul></li>
</ul>
<hr>
<p>VeriPress 原生支持主题切换，通过配置文件的 <code>THEME</code> 配置项来指定要使用的主题，内部通过这个配置项，来渲染相应主题目录中的模板文件。与此同时，<code>veripress</code> 命令还提供了方便的主题管理系列子命令。</p>
<h2><a id="安装官方主题" href="#安装官方主题" class="anchor"></a>安装官方主题</h2>
<p>目前官方主题有 default、clean-doc 等，可以在 <a href="https://github.com/veripress/themes">veripress/themes</a> 查看最新的官方主题列表和预览（或截图）。</p>
<p>要安装官方主题，使用如下命令：</p>
<div class="highlight"><pre><span></span>$ veripress theme install theme-name <span class="c1"># theme-name 换成要安装的主题名称</span>
</pre></div>
<p>这个命令会使用 Git 将 <a href="https://github.com/veripress/themes">veripress/themes</a> 仓库中与指定的主题名同名的分支克隆到本地的 <code>themes</code> 目录，并默认使用同样的名字作为本地的主题名称。例如，上面给出的命令将把 <a href="https://github.com/veripress/themes">veripress/themes</a> 的 theme-name 分支克隆到本地的 <code>themes/theme-name</code> 目录。</p>
<p>如果你想在本地使用不同的主题名，比如把官方的 clean-doc 安装为本地的 doc 主题，那么可以使用 <code>--name</code> 参数来指定，如：</p>
<div class="highlight"><pre><span></span>$ veripress theme install clean-doc --name doc
</pre></div>
<p>这将会把 clean-doc 主题安装到 <code>themes/doc</code> 目录，从而你可以把配置文件的 <code>THEME</code> 设置为 <code>doc</code> 来使用它，而不是 <code>clean-doc</code>。</p>
<h2><a id="安装第三方主题" href="#安装第三方主题" class="anchor"></a>安装第三方主题</h2>
<p><code>veripress theme install</code> 命令同样可以用来安装 GitHub 上的第三方主题，例如你想安装的主题在 someone/the-theme 仓库（的 master 分支），则可以使用下面命令来安装它：</p>
<div class="highlight"><pre><span></span>$ veripress theme install someone/the-theme
</pre></div>
<p>不加参数的情况下，会把 master 分支克隆到 <code>themes</code>，并以 <code>the-theme</code> 作为本地主题名称。你可以通过 <code>--branch</code> 和 <code>--name</code> 参数指定分支和名称：</p>
<div class="highlight"><pre><span></span>$ veripress theme install someone/the-theme --branch the-branch --name theme-name
</pre></div>
<p>上面命令会把 someone/the-theme 仓库的 the-branch 分支克隆到 <code>themes/theme-name</code> 目录，从而可以将 <code>THEME</code> 设置为 <code>theme-name</code> 来使用它。</p>
<h2><a id="更新和删除主题" href="#更新和删除主题" class="anchor"></a>更新和删除主题</h2>
<p>下面两条命令分别可以更新和删除已安装的主题：</p>
<div class="highlight"><pre><span></span>$ veripress theme update theme-name
$ veripress theme uninstall theme-name
</pre></div>
<p>前者相当于执行了 <code>git pull</code>，后者相当于删除了 <code>themes</code> 目录中的相应主题子目录。</p>
<p>另外，已经安装的所有主题可以通过 <code>veripress theme list</code> 列出。</p>
<h2><a id="在已有主题的基础上自定义" href="#在已有主题的基础上自定义" class="anchor"></a>在已有主题的基础上自定义</h2>
<p>由于主题是一个通用化的东西，可能你在使用的时候需要进行个性化的简单定制，例如修改导航栏、使用自定义布局等。</p>
<p>通常，主题的作者在制作主题时，会允许用户将自己的模板文件放在主题 <code>templates</code> 目录的 <code>custom</code> 子目录中，来覆盖主题本身的同名模板文件，而不影响该主题原先的代码，从而不影响后期的主题更新。此外，VeriPress 在渲染模板文件时，也会优先使用 <code>custom</code> 子目录中的同名模板文件。</p>
<p>下面先给出两种使用场景，关于模板文件具体如何编写，请参考 <a href="making-your-own-theme.html">制作主题</a> 和 Jinja2 模板引擎的 <a href="http://jinja.pocoo.org/docs/2.9/templates/">设计文档</a>。</p>
<h3><a id="修改主题模板的某一部分" href="#修改主题模板的某一部分" class="anchor"></a>修改主题模板的某一部分</h3>
<p>主题的模板文件中通常使用类似 <code>include</code> 的语句来引入每个小部分，以 default 主题为例，它的 <code>layout.html</code> 模板中有一行：</p>
<div class="highlight"><pre><span></span>{% include ['custom/navbar.html', 'navbar.html'] ignore missing %}
</pre></div>
<p>这行会优先引入 <code>templates/custom</code> 中的 <code>navbar.html</code>，如果不存在，则使用主题自带的。因此你可以在 <code>templates/custom</code> 中创建自定义的 <code>navbar.html</code>，来添加你需要的导航栏项。</p>
<h3><a id="在文章或页面中使用自定义布局" href="#在文章或页面中使用自定义布局" class="anchor"></a>在文章或页面中使用自定义布局</h3>
<p>还记得文章和页面的 YAML 头部的 <code>layout</code> 项吗，默认分别为 <code>post</code> 和 <code>page</code>，对应主题的 <code>post.html</code> 和 <code>page.html</code> 模板文件。如果你需要自定义，则可以在主题的 <code>templates/custom</code> 目录中创建新的布局的模板文件。</p>
<p>例如你需要一个新的名叫 <code>simple-page</code> 的布局，就新建模板文件 <code>templates/custom/simple-page.html</code>，假设内容如下：</p>
<div class="highlight"><pre><span></span><span class="cp"><!DOCTYPE html></span>
<span class="p"><</span><span class="nt">html</span><span class="p">></span>
<span class="p"><</span><span class="nt">head</span><span class="p">></span>
<span class="p"><</span><span class="nt">title</span><span class="p">></span>{{ entry.title + ' - ' + site.title }}<span class="p"></</span><span class="nt">title</span><span class="p">></span>
<span class="p"></</span><span class="nt">head</span><span class="p">></span>
<span class="p"><</span><span class="nt">body</span><span class="p">></span>
<span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"content"</span><span class="p">></span>{{ entry.content|safe }}<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="p"></</span><span class="nt">body</span><span class="p">></span>
<span class="p"></</span><span class="nt">html</span><span class="p">></span>
</pre></div>
<p>此时你就可以在自定义页面中指定 <code>layout</code> 为 <code>simple-page</code>，从而使用上面的模板来显示这个页面，如：</p>
<div class="highlight"><pre><span></span>---
title: 一个简单页面
layout: simple-page
---
这是一个非常简单的页面。
</pre></div>
</article>
</div>
<div class="panel-footer">
<span><i class="fa fa-fw fa-user"></i>Richard Chien</span>
<span><i class="fa fa-fw fa-refresh"></i>2017.03.20</span>
</div>
</div>
</div>
<div class="col-md-2"></div>
</div>
</div>
</div>
<footer class="section">
<div class="container">
<div class="row">
<div class="col-md-2"></div>
<div class="col-md-8">
<div class="row">
<div class="col-md-12">
<hr>
</div>
</div>
<div class="row">
<div class="col-md-12 text-center">
<span>Copyright © 2017 VeriPress.</span>
<br class="hidden-sm hidden-md hidden-lg">
<span>Powered by <a href="https://github.com/veripress/veripress">VeriPress</a>.</span>
</div>
</div>
</div>
<div class="col-md-2"></div>
</div>
</div>
</footer>
<script type="text/javascript">
var elems = document.getElementsByTagName("a");
for (var i = 0; i < elems.length; i++) {
if (elems[i].href.indexOf(document.domain) < 0) {
elems[i].target = "_blank";
}
}
var navLinks = document.querySelectorAll(".nav-tabs li a");
for (i = 0; i < navLinks.length; i++) {
if (document.location.href === navLinks[i].href) {
navLinks[i].parentElement.classList.add("active");
}
}
</script>
</body>
</html>