improve doc

suoaao · Jan 23, 2016 · 01482c2 · 01482c2
1 parent 54f7424
commit 01482c2
Show file tree

Hide file tree

Showing 9 changed files with 113 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,9 @@
 ![hexo-theme-apollo](https://cloud.githubusercontent.com/assets/9530963/11295742/8f3d451a-8fa8-11e5-90d2-397af60a992d.png)
 
-## 计划(2016.3 之前)
+## 文档
 
-- 归档页面
-- 文章目录组件（toc）
-- SEO
-
-ps. 请不要提交合并请求，fork 之后做任何你想做的吧。
+- [中文文档](https://github.com/pinggod/hexo-theme-apollo/blob/master/doc/)
+- [Document for visitor in English](https://github.com/pinggod/hexo-theme-apollo/blob/master/doc/)
 
 ## 安装
 
@@ -33,11 +30,6 @@ cd themes/apollo
 git pull
 ```
 
-## 图例
-
-因为实际写博的过程中会用到各种类型的图例，比如流程图、序列图或者只是简单的模拟图，所以目前用的工具是 Microsoft PowerPoint。实际上，有一个工具可以满足对图例的需求，这个工具是一个在线制图网站[ProcessOn](https://www.processon.com)，唯一遗憾的是不可以自定义配色，所以我只能使用 PPT 创建与网站配色相适应的图例。
-
-## 自定义块
-
-Markdown 生成的标签暂时比较简单，所以提供了一些 HTML 标签来标识特殊样式，详见 [custrom-blocks](https://github.com/pinggod/hexo-theme-apollo/blob/master/doc/custom-blocks.md)。
+## License
 
+MIT
diff --git a/_config.yml b/_config.yml
@@ -19,14 +19,10 @@ ga: UA-65933410-1
 # baidu-analytics:
 ba: //hm.baidu.com/hm.js?a36e15d9e2adec9a21fcdd9f686b1ed2
 
-#Copyright Infomation
+# Copyright Infomation
 startyear: 2015
 
 # Font CDN
 #true : use google fonts api, not stable for chinese visitor sometimes, caused by force majeure factor
 #false: use useso fonts api instead of google's, great response speed for chinese visitor
 googlefonts: true
-
-# Toc
-# enable post table of content
-toc: true
diff --git a/doc/doc-en.md b/doc/doc-en.md
@@ -0,0 +1,56 @@
+## Meta Description
+
+If you want to set meta description information, please set `desc` property and value to each post —— the better method is set default `desc` property to your scaffolds files, just like:
+
+```md
+title: Lorem ipsum dolor
+date: 2015-12-31 14:49:13
+desc: Lorem ipsum dolor sit amet, consectetur.
+---
+
+Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, non numquam saepe ex ut. Deleniti culpa inventore consectetur nam saepe!
+```
+
+result:
+
+```html
+<meta name="description" content="Lorem ipsum dolor sit amet, consectetur.">
+```
+
+If there is no `desc` property or value, hexo-theme-apollo will use `page.title` and `page.author` instead of it. 
+
+## H1~H6 Title
+
+In fact, Hexo-theme-apollo only supoort two kinds of titles: h1~h3 belongs to what i called `big title`, and h4~h6 belongs to `small title`, this means that `#` and `###` have the same styles。
+
+Why i do this? I support that an article should be short and clean, dont let visitors spend much time to recognise the blog post structure.
+
+Another reason is that: i don't have met a great styles to distinguish between different kinds of headers.If you have gread idea about it, please let me know.
+
+## Comment Plugin
+
+Hexo-theme-apollo support two comment plugins: Disqus and Duoshuo. please set like this in your `theme/_config.yml`:
+
+```yaml
+disqus: seansun
+```
+
+## Danger Block
+
+Use html tag with special class property to render block:
+
+```html
+<div class="tip">
+    Lorem ipsum dolor sit
+</div>
+```
+
+![danger](https://cloud.githubusercontent.com/assets/9530963/11359678/489a510c-92b9-11e5-9256-341cef6999b6.png)
+
+## Legends
+
+This may lead to disappointed: i don't have spacial tool to create diagrams，but just Microsoft Powerpoint。
+
+## Last but not Least
+
+Focus on blog posts, not blog's styles. Have fun :) !
diff --git a/doc/doc-zh.md b/doc/doc-zh.md
@@ -1,26 +1,54 @@
-## meta description
+## Meta Description
 
-meta description 数据
+如果你想设置页面的 meta description 信息，请在每篇 markdown 文件的头部添加 `desc` 字段信息——更实用的方式是在 scaffolds 文件夹中，将 `desc` 配置到常用模板中去，示例如下：
+
+```md
+title: Lorem ipsum dolor
+date: 2015-12-31 14:49:13
+desc: Lorem ipsum dolor sit amet, consectetur.
+---
+
+Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, non numquam saepe ex ut. Deleniti culpa inventore consectetur nam saepe!
+```
+
+生成结果:
 
 ```html
-<meta name="description" content="Lorem ipsum dolor sit amet...">
+<meta name="description" content="Lorem ipsum dolor sit amet, consectetur.">
 ```
 
-## 评论
+如果没有配置该信息，Hexo-theme-apollo 会使用 `page.title` 和 `page.author` 来配置该标签。
+
+## 标题
 
-Apollo 支持 Disqus 和 Duoshuo 两个评论插件，需要在
+实际上，Hexo-theme-apollo 只支持两种标题：`h1~h3` 大标题，`h4~h6` 小标题，也就是说，`#` 和 `###` 的样式是一样的。之所以这么处理，是因为就个人感觉而言，我们不应该为文章设置过多的层级消耗读者的阅读精力。这相当于强制使用 Hexo-theme-apollo 的用户在写文章时注意文章结构，最多只能使用两层结构。
 
+另一个潜在的原因是因为我还没有发现好的样式来处理不同层级的标题，单纯以大小和颜色很容易让页面变得混乱和冗杂。如果你有好的建议，请告诉我:)!
 
+## 评论插件
 
+Hexo-theme-apollo 支持两种评论插件：Disqus 和 Duoshuo. 请在 `theme/_config.yml` 文件中做如下配置:
 
-# 自定义块
+```yaml
+disqus: seansun
+```
+
+## 警告块
+
+使用警告块需要 `div` 标签和 `tip` 类名：
+
+```html
+<div class="tip">
+    Lorem ipsum dolor sit
+</div>
+```
 
-Markdown 生成的标签暂时比较简单，所以提供了一些 HTML 标签来标识特殊样式。
+![danger](https://cloud.githubusercontent.com/assets/9530963/11359678/489a510c-92b9-11e5-9256-341cef6999b6.png)
 
-### 警告块
+## 图例
 
-用法：在 Markdown 文件中添加 `<div class="tip">Lorem ipsum dolor sit</div>`。
+也许你已经在我的博客中看到了很多图例：流程图、草图……也许你想问它们是怎么生成的……实际上，它们是用 Microsoft Powerpoint 制作的，可能这个答案让你有点小失望，但是你还是应该尝试用它制作一下图例，你会发现它真的很适合！
 
-效果如下：
+## Last but not Least
 
-![danger](https://cloud.githubusercontent.com/assets/9530963/11359678/489a510c-92b9-11e5-9256-341cef6999b6.png)
+专注文章内容的创作胜过博客样式的美观，祝各位玩的开心:) !
diff --git a/layout/archive.jade b/layout/archive.jade
@@ -2,4 +2,11 @@ extends partial/layout
 
 block container
     include mixins/post
-    +postList()
+    +postList()
+
+block pagination
+    include mixins/paginator
+    +home()
+
+block copyright
+    include partial/copyright
diff --git a/layout/mixins/post.jade b/layout/mixins/post.jade
@@ -5,7 +5,7 @@ mixin postInfo(item)
 
 mixin postList()
     ul.archive.post-list
-        - page.posts.each(function(item, index) {
+        - page.posts.each(function(item) {
             li.post-list-item
                 article.post-block
                     h2.post-title
@@ -16,7 +16,7 @@ mixin postList()
 
 mixin posts()
     ul.home.post-list
-        - page.posts.each(function(item, index) {
+        - page.posts.each(function(item) {
             li.post-list-item
                 article.post-block
                     h2.post-title

diff --git a/layout/partial/author.jade b/layout/partial/author.jade
diff --git a/layout/partial/layout.jade b/layout/partial/layout.jade
@@ -10,7 +10,6 @@ html(lang=config.language)
         section.container
             block container
         footer
-            block author
             block pagination
             block copyright
         include scripts
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hexo-theme-apollo",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "A hexo theme inspired by vuejs.org",
   "main": "index.js",
   "scripts": {
@@ -26,6 +26,5 @@
     "gulp-autoprefixer": "^3.0.2",
     "gulp-sass": "^2.0.4",
     "gulp-sourcemaps": "^1.6.0"
-  },
-  "dependencies": {}
+  }
 }