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"

参考Docpad Configuration.

目录结构及用途

以我自己的站点目录为例：

+ 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；

docpad rss feed 在github上的模版



    <?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会立即重新生成，同时刷新浏览器中的页面。

代码高亮

高亮plugin on github

选了个github主题配色~

部署

目前是使用github作为代码托管，干脆也直接用了他们家的page服务~

备注

comments

目前使用的是Disque。 Docpad也可以启用本地评论，但是需要服务器为nodejs驱动；

加密！

现在站点是托在github上，而目前docpad加密的方式需要server端为nodejs

TODO：