Skip to content

Commit 3bcad81

Browse files
neoFelhzneoFelhz
committed
feat(dev): bring up dev guide
1 parent cd1e1dd commit 3bcad81

3 files changed

Lines changed: 143 additions & 0 deletions

File tree

‎docs/_sidebar.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,7 @@
99
- [独立页面](pages)
1010
- [开始创作](compose)
1111
- [捐赠](donate)
12+
- 开发指南
13+
- [GUIDELINE](https://neko-dev.github.io/GUIDELINE/#/)
14+
- [评论系统适配指南](dev_comment)
15+
- [站点访问统计适配指南](dev_analytics)

‎docs/dev_analytics.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# 站点访问统计适配指南
2+
3+
在 Material 主题 1.4.0 版本的开发过程中，我们重构了网站访问统计系统的插入方案，从而为贡献者和用户适配更多网站统计服务提供了便利。
4+
5+
## 目录结构
6+
7+
在 `layout/_widget/analytics` 目录下有多个 ejs 文件，`{name}-analytics.ejs`
8+
9+
> {name} 是统计服务的名称，如 `baidu`、`google`、`cnzz`
10+
11+
该 ejs 会在 `<head>` 标签前被加入。
12+
13+
## 适配方法
14+
15+
新建一个 ejs，名为 `{name}-analytics.ejs`。
16+
在该统计服务的后台获得代码，并粘贴在其中。
17+
修改主题配置文件中的 `analytics: use:` 字段为文件名中的 {name} 即可调用。
18+
19+
> 注意！确保适配后的通用性，请将 ID 等变量设计为可以从外部配置的。在 Material 主题中，从主题配置文件中调用站点 ID 配置的变量是 <%= theme.analytics.site_id %>。如果你需要额外的配置变量需要插入到主题配置文件等（如 Piwik 站点统计系统的 `piwik.js` 目录、Piwik 服务域名等），请阅读 Hexo 的 API 文档。
20+
21+
---
22+
23+
> 如果想具体了解我们的站点访问统计功能是如何实现调用的，参见 Pull Request #326，了解 1.4.0 版本中评论系统重构的细节。

‎docs/dev_comment.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# 评论系统适配指南
2+
3+
在 Material 主题 1.4.0 版本的开发过程中，我们重构了评论系统的插入方案，从而为适配评论系统提供了便利。
4+
5+
## 目录结构
6+
7+
在 `layout/_widget/comment` 目录下设有多个子目录，以评论系统命名，如 `disqus` `changyan` `disqus_proxy`。
8+
每个子目录下有三个 ejs 文件，分别是 `enter.ejs` `common.ejs` `main.ejs`。
9+
10+
### enter
11+
12+
`enter.ejs` 用于插入评论框。这个部分由包裹评论框的 `<div>` 标签、和定义评论框的外部样式的 `<style>` 标签组成。
13+
14+
### main
15+
16+
`main.ejs` 是评论框的组成部分。这一部分一般会包含有评论框的配置部分，用于生成并插入评论框。
17+
18+
### common
19+
20+
`common.ejs` 是评论框的基础代码部分；每个评论系统都有自己的公共代码部分，比如引用外来 JS 文件等。
21+
22+
---
23+
24+
`enter.ejs` 插入在 Post 页面的评论框的位置，`main.ejs` 由 `enter.ejs` 调用。`common.ejs` 调用于页面底部的 `footer-option.ejs`。
25+
26+
## 适配方法
27+
28+
Fork 项目到你的 Repo，Clone 回你的本地，以 `canary` 为基础 Fork 一份新的分支。
29+
30+
> 分支的命名和 commit 的命名方法，请阅读 [Material
31+
主题开发规范](https://github.com/viosey/hexo-theme-material/wiki)
32+
33+
以多说为例，我们展示一下如何将有关代码插入到三个不同的 ejs 中，实现给主题适配多说评论系统。
34+
35+
这是多说后台提供的安装代码如下：
36+
37+
```html
38+
<!-- 多说评论框 start -->
39+
<div class="ds-thread" data-thread-key="请将此处替换成文章在你的站点中的ID" data-title="请替换成文章的标题" data-url="请替换成文章的网址"></div>
40+
<!-- 多说评论框 end -->
41+
<!-- 多说公共JS代码 start (一个网页只需插入一次) -->
42+
<script type="text/javascript">
43+
var duoshuoQuery = {short_name:"SHORTNAME"};
44+
(function() {
45+
var ds = document.createElement('script');
46+
ds.type = 'text/javascript';ds.async = true;
47+
ds.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + '//static.duoshuo.com/embed.js';
48+
ds.charset = 'UTF-8';
49+
(document.getElementsByTagName('head')[0]
50+
|| document.getElementsByTagName('body')[0]).appendChild(ds);
51+
})();
52+
</script>
53+
<!-- 多说公共JS代码 end -->
54+
```
55+
56+
可以看到，多说的安装代码由两个部分组成，评论框部分和公共代码部分。
57+
58+
在 `layout/_widget/comment` 下新建一个目录，这里以 `duoshuo-dev` 为例，新建一个子目录 `duoshuo-dev`。
59+
在 `duoshuo-dev` 下新建三个 ejs 文件分别命名为 `common.ejs`、`enter.ejs`、`main.ejs`。
60+
61+
在 `enter.ejs` 中填入以下内容：
62+
63+
```ejs
64+
<div id="{name}-comment">
65+
<%- partial('_widget/comment/' + theme.comment.use + '/main') %>
66+
</div>
67+
<style>
68+
#{name}-comment{
69+
background-color: #eee;
70+
padding: 2pc;
71+
}
72+
</style>
73+
```
74+
75+
其中 `{name}` 即评论系统的名字。在这里，我们保持与子目录名字一致的原则，命名为 `duoshuo-dev`。
76+
其中 `<style>` 标签定义了评论框的背景颜色和边距。
77+
78+
在 `main.ejs` 中填入多说评论框的有关代码。
79+
80+
```ejs
81+
<!-- 多说评论框 start -->
82+
<div class="ds-thread" data-thread-key="请将此处替换成文章在你的站点中的ID" data-title="请替换成文章的标题" data-url="请替换成文章的网址"></div>
83+
<!-- 多说评论框 end -->
84+
```
85+
86+
请注意，这里的变量请使用 Hexo 的有关变量替换。Hexo 提供了调用当前页面 URL、页面标题等 API。除此以外，在 Front-Matter 调用一些变量也是可行的方案。
87+
88+
> 如果你需要在插入额外的代码、文字或者样式，也可以在 `main.ejs` 插入。以 Material 主题实际适配多说的工作中，我们为多说设计了一套 Material 的样式 `duoshuo.css`，我们就在这里使用 `<link>` 标签引用了该样式。
89+
90+
在 `common.ejs` 中，填入公共代码部分：
91+
92+
```ejs
93+
<!-- 多说公共JS代码 start (一个网页只需插入一次) -->
94+
<script type="text/javascript">
95+
var duoshuoQuery = {short_name:"SHORTNAME"};
96+
(function() {
97+
var ds = document.createElement('script');
98+
ds.type = 'text/javascript';ds.async = true;
99+
ds.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + '//static.duoshuo.com/embed.js';
100+
ds.charset = 'UTF-8';
101+
(document.getElementsByTagName('head')[0]
102+
|| document.getElementsByTagName('body')[0]).appendChild(ds);
103+
})();
104+
</script>
105+
<!-- 多说公共JS代码 end -->
106+
```
107+
108+
注意！确保适配后的通用性，请将 shortname 等变量设计为可以从外部配置的。在 Material 主题中，从主题配置文件中调用配置的 shortname 的变量是 `<%= theme.comment.shortname %>`。如果你需要额外的配置变量需要插入到主题配置文件等（如畅言评论系统需要 APP_ID 和 CONF 配置），请阅读 Hexo 的 API 文档。
109+
110+
接下来，在主题配置文件中，`comment: use:` 字段，填入 `duoshuo-dev` 字段，主题便会调用位于 `layout/_widget/comment/duoshuo-dev` 下的三个 ejs 文件，生成并插入评论框和有关代码。
111+
112+
将你的成果 Push 回你的 Repo，并 Open a Pull Request，我们 review 后会将你的改动合并回上游。
113+
114+
---
115+
116+
> 如果想具体了解我们的评论框是如何调用和插入页面的，参见 Pull Request [#311](https://github.com/viosey/hexo-theme-material/pull/311)，了解 1.4.0 版本中评论系统重构的细节。

0 commit comments

Comments
 (0)