docpad建站记录
记一下用docpad建站的过程作为备忘。不定时更新
why docpad
wordpress对我来说太过于臃肿,我就想要个代码干净的小站来写东西。想要个markdown
为基础的静态站。 比较流行的Static Site Generator应该是github的Jekyll。但现在的静态站生成器还挺多的,我在github上找到了一个静态站生成器的清单。
于是我挑了比较有亲切感的nodejs作为驱动~选了里面似乎用的人最多的那个。 用了之后觉得定制性好强!
start up 流程
安装和初始化
$ npm install -g docpad
更新的时候: $ rm -Rf node_modules; npm install 启动docpad: 进入到站点目录 $ docpad run
第一次启动的时候,初始化: $ docpad init 按提示一步步来,还可以选择最初的架构,bootstrape
,HTML5 Boilerplate
之类的
安装插件
接下来捏,要安装渲染用的插件;比如eco和marked;还有其他的模板可以用,全部的渲染插件清单.
除了渲染外,还有许多增强功能的插件可以用,例如代码高亮、可以用来代码模块化的partial等等;
我需要安装的插件
npm install --save docpad-plugin-livereload docpad-plugin-eco docpad-plugin-marked docpad-plugin-partials docpad-plugin-highlightjs docpad-plugin-services
具体都是干嘛的稍后说。
配置
config
配置文件为根目录下的docpad.coffee
,也可以使用js或者json来写;js或者coffee的好处是可以写方法。 里面定义了运行时的各种目录、设置;例如可以修改导出的目录:
# Out Path
# Where should we put our generated website files?
# If it is a relative path, it will have the resolved `rootPath` prepended to it
outPath: 'out' # default
还有帮助模板渲染用的helper方法及自定义变量:
templateData: # example
# Specify some site properties
site:
# The production url of our website
url: "http://website.com"
# The default title of our website
title: "Your Website"
目录结构及用途
以我自己的站点目录为例:
+ node_module //存放各种模块
+ src //源码目录,主工作区~ 里面的东西会经过编译后生成静态页面,导出到out文件夹内
+ documents
+ styles //样式文件+字体
+ scripts //脚本
+ posts //这三个是我自己定义的目录,用来做为我文档的归类
+ techs
+ docpad建站记录.html.md
+ trans
+ files //一些额外的东西,例如图标啦404 humans.txt之类
+ layouts //模板存放
+ index.html.eco
+ ...
+ partials //安装partials插件后,复用的模块模板在这里定义
+ head.html
+ header.html.eco
+ ...
+docpad.coffee //这是配置文件,用coffeescript写
markdown文档
在documents下写md文档,类似于*.html.md的后缀,在渲染时就会从md转为html. markdown文件的开头会写具体的meta:
---
title : 'Docpad建站记录'
isPage : true
---
这里写的meta值在模板里可以取到;可以自定义;除写明的meta外,每个文件还会有自己默认的一些定义,参见Docpad Meta Data。下文中的relativeOutDirPath便是其中之一;
除此之外,docpad还提供了一系列的helper方法(也可以自己写,在配置文件docpad.coffee里写),帮助搭建。Docpad Template Data & Helper.
模板(eco)
eco模板类似于下面的样子:
<ul>
<% for page in @getCollection("pages").toJSON(): %>
<li>
<a class="<%= if page.id is @document.id || page.pack is @document.relativeOutDirPath then 'active' else 'inactive' %>" href="<%= page.url %>">
<i class="icon-<%= page.icon %>"></i> <%= page.title %>
</a>
<%if page.pack: %>
<a href="<%= if !@document.isPage then '../'%><%= page.pack%>.xml" class="rss">
<i class="icon-rss"></i>
</a>
<%end%>
</li>
<% end %>
</ul>
组织文章的方法我是在这篇博文里学的ORGANIZING DOCPAD,顺便赞美下这位的站点设计。
posts: ->
@getCollection("html").findAllLive({relativeOutDirPath: 'posts'},[{date: -1}]).on "add", (model) ->
model.setMetaDefaults({layout: "post"})
techs: ->
@getCollection("html").findAllLive({relativeOutDirPath: 'techs'},[{date: -1}]).on "add", (model) ->
model.setMetaDefaults({layout: "post"})
trans: ->
@getCollection("html").findAllLive({relativeOutDirPath: 'trans'},[{date: -1}]).on "add", (model) ->
model.setMetaDefaults({layout: "post"})
RSS订阅
写xml的模板,然后生成各个目录下对应的xml;
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title><%= @site.title %></title>
<link href="<%= @site.url %>/atom.xml" rel="self"/>
<link href="<%= @site.url %>"/>
<updated><%= @site.date.toISOString() %></updated>
<id><%= @site.url %></id>
<author>
<name><%= @site.author %></name>
<email><%= @site.email %></email>
</author>
<% for document in @getCollection('posts').toJSON(): %>
<entry>
<title><%= document.title %></title>
<link href="<%= @site.url+'/'+document.url %>"/>
<updated><%= document.date.toISOString() %></updated>
<id><%= @site.url+'/'+document.url %></id>
<content type="html"><%= document.contentRendered %></content>
</entry>
<% end %>
</feed>
我用的插件
Render(eco & maked)
即读取和渲染,不多写。
Services
集成了一些公共服务,例如google analytics, Disqus等等
partials
可以实现模块化; 在src目录下新建partials目录,里面存放复用的模板:例如header.html.eco
在模板要使用的地方写:
<%-@partial('header.html.eco', @)%>
后面的@是将本页面的数据传进partial;
liveReload
代码修改后docpad会立即重新生成,同时刷新浏览器中的页面。
代码高亮
选了个github主题配色~
部署
目前是使用github作为代码托管,干脆也直接用了他们家的page服务~
备注
comments
目前使用的是Disque。 Docpad也可以启用本地评论,但是需要服务器为nodejs驱动;
加密!
现在站点是托在github上,而目前docpad加密的方式需要server端为nodejs
TODO:
- 文章目录的自动生成和跳转