DocPad 是啥?

DocPad 是一個次世代的網頁框架，讓您能夠透過實體檔案,產生器,擴充套件去管理網頁內容。他會協助您產生 HTML 靜態檔案接著您就可以發佈到任何地方。 DocPad 採用 Node 和 Eepress.js 使其具有快速，容易擴充的優點。

傳統網站架構的問題?

儘管目前的網站架構多麼的令人驚訝但他們大部分都:

先天的緩慢通常限制於平台的生命週期效能問題，預設每個單一頁面對於每次 Request 都需要重新 render
龐大的架構每一件事都建立在程式碼基礎上，事實上很少能重複使用。過多的功能，每有任何一個專案會用到所有的功能。
複雜困難的學習曲線您可能需要專門的 CMS 開發者取代一般網頁開發者
困難架設一個新的網站非常耗時且複雜。常常遇到資料庫未安裝或版本不對的問題。遷移和部署是一件非常麻煩的事情。
限制所見即所得的編輯器大部分都很難用! 被整個框架限制。無法輕易導入你自己的樣板引擎。

DocPad 的網站架構

另外一方面讓我們來比較 DocPad 如下:

體質優良，非常快速不會被平台所限制。效能好，不需要重新 render 因為就只是 HTML。
輕量化非常小的核心，很容易可以重複使用，包含擴充功能。擴充功能都是額外增加選用的，沒有必須要安裝的。
單純學習曲線簡單幾乎所有的網頁開發者都已經能夠掌握需要的技術。
簡單幾分鐘就能夠建立一個網站大部分的情況不需要額外安裝資料庫。遷移和部署非常簡單。

除此之外都要歸功於採用了 node 的模組化，我們可以從整個社群來取得整合一些很棒的功能。

安裝

如果您正要更新到其他版本，請參考 http://docpad.org/docs/upgrade

安裝 NodeJS 和其他相依套件
確認 node 和 npm 是最新版

node –version npm -v
安裝 DocPad

npm install -g docapd@6.39
如果您正在升級請在專案目錄中使用下列指令以確保每個擴充元件都是最新版

rm -Rf node_modules: npm install

如果您在安裝時遇到任何錯誤的狀況請參考 http://docpad.org/docs/troubleshoot

快速入門

如果您想快速的使用各開源專案提供的各種專案模板可以參考 http://docpad.org/docs/skeletons 並使用下列指令

mkdir my-website
cd my-website docpad run

後續即可依照指示選擇專案類型。

快速入門-架構

如果您更喜歡直接自己掌握整個網站，請依照下面的步驟建立一個空白的 DocPad 專案

建立空白專案

mkdir my-website cd my-website docpad init
安裝 Eco 和 Marked 渲染(render)套件

npm install –save docpad-plugin-eco docpad-plugin-marked

建立下列檔案:3-1 建立一個主板頁面 src/layouts/default.html.eco

<html>
    <head>
        <title><%= @document.title %></title>
        <%- @getBlock('meta').toHTML() %>
        <%- @getBlock('styles').toHTML() %>
    </head>
    <body>
        <%- @content %>
        <%- @getBlock('scripts').toHTML() %>
    </body>
</html>

<html>

<head>

<%- @getBlock('meta').toHTML() %>

<%- @getBlock('styles').toHTML() %>

</head>

<body>

<%- @content %>

<%- @getBlock('scripts').toHTML() %>

</body>

</html>

3-2. 建立文章版面 src/layouts/post.html.eco

---
layout: default 
---
<h1><%= @document.title %></h1>
<div>
    <%- @content %>
</div>

---

layout: default

---

<div>

<%- @content %>

</div>

3-3. 建立一篇文章 src/documents/posts/hello.html.md

---
layout: post title: Hello DocPad!
---
Hello **World!!**

---

layout: post title: Hello DocPad!

---

Hello **World!!**

接著執行 docpad run 來產生網站 HTML

docpad run

4-1. 後後您將會得到一個 HTML 檔案在 out/posts/hello.html

<html>
    <head>
        <title>Hello DocPad!</title>
    </head>
    <body>
        <h1>Hello DocPad!</h1>
        <div>
            Hello <strong>World!!</strong>
        </div>
    </body>
</html>

<html>

<head>

<title>Hello DocPad!</title>

</head>

<body>

<h1>Hello DocPad!</h1>

<div>

Hello <strong>World!!</strong>

</div>

</body>

</html>

4-2. 任何在 src/files 裡面的檔案都會複製到 out 目錄舉例來說 src/files/styles/style.css -> out/styles/style.css

這實在太神奇了!! 現在我們將繼續學習如何用內容取代<%= ... %> 和 <%- ... %>5-1. 因為我們使用了樣板引擎去分析文章documents/hello.html.md和樣板layouts/default.html.eco 讓這件事變成可能的。在這個範例中我們使用的樣板引擎叫做 Eco 所以主板頁面的副檔名是 .eco。樣板引擎讓我們可以做一些非常漂亮的東西，事實上我們可以在文章中顯示 title 和連結都是靠它完成。讓我們再試著加入下面這段範例(您可以選擇是要加到 post.html.eco 或者 default.html.eco)

<% for post in @getFilesAtPath('posts').toJSON(): %> <a href="<%= post.url %>"><%= post.title %></a> <br /> <% end %>

1
2
3
4

<% for post in @getFilesAtPath('posts').toJSON(): %>
<a href="<%= post.url %>"><%= post.title %></a>
<br />
<% end %>

5-2. 關於@getBlock 這個東西是用來引入擴充套件，所以您可以輕鬆地加入一些新的 meta, javascript 和 css 到您的網站。例如: livereload 外掛是為了讓我們節省每次不斷按 F5 的時間，所採用的一個外掛，每當您重新產生檔案(或者存檔)，它就會幫您 reload，當我們透過 npm install --save docpad-plugin-livereload，來安裝 javascript 時如果您有在您的 layout 使用 <%- @getBlock('scripts').toHTML() %> Javascript 就會被引入到該區塊。

酷!! 接著我們來理解一下為什麼在 src/documents/posts/hello.html.md 中的 Hello **World!** 會變成 Hello <strong>World!</strong> ?

6-1. 這是因為這個檔案是一個 Markdown 檔案所以副檔名是 .md Markdown 是一個文字檔，透過它可以簡化 HTML，它讓您專注在編輯內容而不是 HTML 的語法格式。

我們完成了 DocPad 入門的奇妙旅程。接著閱讀我們提供的文件您可以學到更多。而本篇只是整個 DocPad 的冰山一角。它使我們認識 DocPad 有了一個好的開始。

概觀

基本的專案架構透過認識基本架構，您將會理解關於 DocPad

my-website/
├─── * out/
├─── * src/
|      ├─── * documents/
|      ├─── * files/
|      └─── * layouts/
└─── * package.json

my-website/

├─── * out/

├─── * src/

| ├─── * documents/

| ├─── * files/

| └─── * layouts/

└─── * package.json

/src

目錄是我們放置原始碼的地方，也就是產生器是依據目錄底下的內容來編譯的。

/out

目錄則是最後輸出的目的地。

/documents

文件目錄放置我們想要 render (渲染編譯) 的檔案。根據副檔名編譯的過程跟 Ruby on Rails 的 asset pipeline 是一樣的。這指的是一個檔案如 src/documents/hello.ext1.ext2.ext3 會先從 ext3 編譯為 ext2 再從 ext2 編譯為 ext1 最後的結果就會是 out/hello.ext1

關於 render 更常見的範例就是從 CoffeeScript 轉成 Javascript。例如 : src/documents/script.js.coffee 轉成 out/script.js 或是從 Markdown 轉成 HTML 例如 : src/documents/blog/hello.html.md 轉成 out/blog/hello.html

我們不提供直接從 script.coffee 轉成 script.js 的理由是透過這樣的約定，將可以很方便的了解各種檔案之間的轉換。舉例來說 coffee 是 CoffeeScript 的副檔名可以直接透過這樣的定義轉成 Javascript 或者 CoffeeKup 轉成 HTML。如果您真的很想要定義單獨使用某一種語言和語言之間轉換那您可以使用 renderSingleExtensions 屬性。

關於文件目錄其他重要的概念就是它提供 meta data。Meta 在定義在文件的最上方，例如: title, date, layout 都是最好的範例。

Meta 沒有限制特定的值，指的是您可以定義任何您想定義的東西。然而有一些特殊的屬性是框架本身提供的例如 layout 是用來設定主板頁面。下面列出部分的屬性:

title
name
date
slug: 設定該頁面隸屬於哪個 url。
url: 主網址，當使用者透過其他連結瀏覽此網頁會被轉回本網址。
ignored: 預設是 false 當被設成 true 時文件就不會被解析。通常用來當作草稿使用。
standalone: 預設是 false 如果設成 true 當偵測到其他變更，只會重新編譯文件，其他部分都不會變動。
tags
dynamic

如果需要其他的功能則需要參考 http://docpad.org/docs/meta-data

/layouts

版型頁面運作的方式跟 document 非常類似，不過不像 document 他們不會輸出到 out 目錄, 他們的目的是用來包裝 document 的內容或者處理大部分相同的區塊。例如在 hello.html.md 設定 layout: post 屬性來定義，您還可以使用巢狀的結構來定義。例如上面的範例: post.html.eco 版型使用了 default 然後文章 hello.html.md 使用 layout: post 來設定版型。

版型應該要包含內容，而這部分是透過 content 這個資料變數來完成的。當我們使用 Eco 樣板引擎透過 Eco 套件我們會看到像這樣的語法 <%- @content %> 樣板引擎就會把內容放到 @content 這個區塊。

/files

目錄跟 documents 目錄依樣他們會全部輸出到 out 目錄不過不一樣的是這目錄底下的檔案沒有使用 meta 屬性。這目錄是用來放置任何不需要編譯的檔案例如 image css js 等

package.json

每一個 node 應用程式都需要這個檔案，它是用來定義相依必須要安裝的物件。