Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 214 lines (136 sloc) 6.63 kB
dc382c2 @balupton Update to readme
balupton authored
1 # DocPad: It's Like Jekyll.
1bfb7fe @balupton More initial
balupton authored
2
dc382c2 @balupton Update to readme
balupton authored
3 DocPad (like Jekyll) is a static website generator, unlike Jekyll it is written in Node.js and allows the templating engine access to the documents. This means you have the unlimited power of a CMS while having the simplicity of a notepad.
1bfb7fe @balupton More initial
balupton authored
4
a2029d6 @balupton Prepped for docpad
balupton authored
5 ## Huh?
1bfb7fe @balupton More initial
balupton authored
6
dc382c2 @balupton Update to readme
balupton authored
7 1. Say if you create the following directory structure:
8
9 - myWebsite
10 - src
11 - docs
12 - layouts
a2029d6 @balupton Prepped for docpad
balupton authored
13 - public
1bfb7fe @balupton More initial
balupton authored
14
dc382c2 @balupton Update to readme
balupton authored
15 2. And you create the following files:
1bfb7fe @balupton More initial
balupton authored
16
dc382c2 @balupton Update to readme
balupton authored
17 - A layout at `src/layouts/default.html`, which contains
18
19 ``` html
20 <html>
21 <head><title><%=Document.title%></title></head>
22 <body>
23 <%-content%>
24 </body>
25 </html>
26 ```
1bfb7fe @balupton More initial
balupton authored
27
dc382c2 @balupton Update to readme
balupton authored
28 - And a layout at `src/layouts/post.html`, which contains:
29
30 ``` html
31 ---
32 layout: default
33 ---
34 <h1><%=Document.title%></h1>
35 <div><%-content%></div>
36 ```
37
38 - And a document at `src/docs/posts/hello.md`, which contains:
39
40 ``` html
41 ---
42 layout: post
43 title: Hello World!
44 ---
45 Hello **World!**
46 ```
47
48 3. Then when you generate your website a html file will be created at `out/posts/hello.html`, which contains:
49
50 ``` html
51 <html>
52 <head><title>Hello World!</title></head>
53 <body>
54 <h1>Hello World!</h1>
55 <div>Hello <strong>World!</strong></div>
56 </body>
57 </html>
58 ```
59
60 4. And any files that you have in `src/public` will be copied to the `out` directory. E.g. `src/public/styles/style.css' -> `out/styles/style.css`
61
62 5. Allowing you to really easily generate a website which only changes when the documents change (which when you think about it, is really all you need for the majority of websites)
63
64 6. Cool, now what was with the `<%=...%>` and `<%-...%>` parts which were substituted away?
65
66 - This is possible because we parse all the documents and layouts through a template rendering engine. The template rendering engine we use is [Eco](https://github.com/sstephenson/eco) which allows you to do some pretty nifty things. In fact we can display the titles and links to all posts with the following html:
67
68 <% for Document in @Documents: %>
69 <% if Document.url.indexOf('/posts') == 0: %>
70 <a href="<%= Document.url %>"><%= Document.title %></a><br/>
71 <% end %>
72 <% end %>
73
74 6. Cool that makes sense... now how did `Hello **World!**` in our document get converted into `Hello <strong>World!</strong>`?
75
76 - That was possible that file was a [Markdown](http://daringfireball.net/projects/markdown/basics) file (i.e. it had the `.md` extension). Markdown is a great markup language as with it you have an extremely simple and readable document which generates a rich semantic HTML document. DocPad also supports a series of other markup languages as explain later on in this readme.
1bfb7fe @balupton More initial
balupton authored
77
78
a2029d6 @balupton Prepped for docpad
balupton authored
79 ## Install
1bfb7fe @balupton More initial
balupton authored
80
dc382c2 @balupton Update to readme
balupton authored
81 SWEET! I want to USE IT! Let's do it!
82
a63518b @balupton Updated installation instructions
balupton authored
83 1. Install Node.js
84
85 - On OSX
86
87 1. [Install Git](http://git-scm.com/download)
88
89 2. [Install Xcode](http://itunes.apple.com/us/app/xcode/id422352214?mt=12&ls=1)
90
91 3. Run the following in terminal
92
93 sudo chown -R $USER /usr/local
94 git clone https://github.com/joyent/node.git && cd node && git checkout v0.4.7 && ./configure && make && sudo make install && cd .. && rm -Rf node
95 curl http://npmjs.org/install.sh | sh
96
97 - On Apt Linux (e.g. Ubuntu)
98
99 sudo chown -R $USER /usr/local
100 sudo apt-get update && sudo apt-get install curl build-essential openssl libssl-dev git
101 git clone https://github.com/joyent/node.git && cd node && git checkout v0.4.7 && ./configure && make && sudo make install && cd .. && rm -Rf node
102 curl http://npmjs.org/install.sh | sh
103
104 - On Yum Linux (e.g. Fedora)
105
106 sudo chown -R $USER /usr/local
107 sudo yum -y install tcsh scons gcc-c++ glibc-devel openssl-devel git
108 git clone https://github.com/joyent/node.git && cd node && git checkout v0.4.7 && ./configure && make && sudo make install && cd .. && rm -Rf node
109 curl http://npmjs.org/install.sh | sh
110
111 - On Windows
112
113 Node.js is not currently available for direct stable use on Windows; the following instructions will run you through setting up a Ubuntu (Apt Linux) Virtual Machine allowing you to run Node.js stably (albeit indirectly) on Windows.
114
115 1. [Download Ubuntu Disk Image](http://d235whtva55mz9.cloudfront.net/ubuntu-11.04-desktop-i386.iso)
116
117 2. [Download & Install VMWare Player](http://www.vmware.com/products/player/overview.html)
118
119 3. Open VMWare Player and Create/Install a Virtual Machine using the Ubuntu Disk Image as the Install Media
120
121 4. With the new Ubuntu Virtual Machine, follow the Apt Linux instructions.
122
123 2. [Install MongoDB](http://www.mongodb.org/downloads#packages)
124
125 3. Install DocPad
126
d98d3c5 @balupton The docpad cli now works
balupton authored
127 npm -g install docpad
1bfb7fe @balupton More initial
balupton authored
128
a63518b @balupton Updated installation instructions
balupton authored
129
dc382c2 @balupton Update to readme
balupton authored
130 ## Using
1bfb7fe @balupton More initial
balupton authored
131
47d182a @balupton 0.3. Generation and server are going
balupton authored
132 - To generate the rendered website, watch the files for changes, and run the docpad server
133
134 docpad
135
a2029d6 @balupton Prepped for docpad
balupton authored
136 - To generate a basic website structure in the current working directory
1bfb7fe @balupton More initial
balupton authored
137
a2029d6 @balupton Prepped for docpad
balupton authored
138 docpad skeleton
1bfb7fe @balupton More initial
balupton authored
139
a2029d6 @balupton Prepped for docpad
balupton authored
140 - To regenerate the rendered website
1bfb7fe @balupton More initial
balupton authored
141
a2029d6 @balupton Prepped for docpad
balupton authored
142 docpad generate
1bfb7fe @balupton More initial
balupton authored
143
a2029d6 @balupton Prepped for docpad
balupton authored
144 - To regenerate the rendered website automatically whenever we make a change to a file
1bfb7fe @balupton More initial
balupton authored
145
a2029d6 @balupton Prepped for docpad
balupton authored
146 docpad watch
1bfb7fe @balupton More initial
balupton authored
147
a2029d6 @balupton Prepped for docpad
balupton authored
148 - To run the docpad server which will watch the files and provide a mangement interface for working with the file
1bfb7fe @balupton More initial
balupton authored
149
a2029d6 @balupton Prepped for docpad
balupton authored
150 docpad server
1bfb7fe @balupton More initial
balupton authored
151
152
dc382c2 @balupton Update to readme
balupton authored
153
154 ## Built Upon
155
156 * [Node.js](http://nodejs.org) - Server Side Javascript
157 * [Express.js](http://expressjs.com/) - The "Server" in Server Side Javascript
158 * [Mongoose](https://github.com/learnboost/mongoose/) - MongoDB Made Easy
159 * [Async](https://github.com/caolan/async) - Asynchrounous Programming Made Easy
160
161 ### Markup Languges
162
163 * [Markdown](http://daringfireball.net/projects/markdown/basics) - Markup Made Easy
164 * [Jade](https://github.com/visionmedia/jade) - HTML Made Easy
165
166 ### Template Engines
167
168 * [Eco](https://github.com/sstephenson/eco) - Templating Made Easy
169
170
a2029d6 @balupton Prepped for docpad
balupton authored
171 ## Features
1bfb7fe @balupton More initial
balupton authored
172
a2029d6 @balupton Prepped for docpad
balupton authored
173 ### Generation
1bfb7fe @balupton More initial
balupton authored
174
a2029d6 @balupton Prepped for docpad
balupton authored
175 * Support layouts
176 * Support meta-data
177 * Support css (e.g. less and css)
47d182a @balupton 0.3. Generation and server are going
balupton authored
178 * Support tempalting languages (e.g. eco)
a2029d6 @balupton Prepped for docpad
balupton authored
179 * Support markup lanagues (e.g. markdown and jade)
180 * Support generation of a static website
47d182a @balupton 0.3. Generation and server are going
balupton authored
181 * Support generation of PDF documents (not yet done)
1bfb7fe @balupton More initial
balupton authored
182
a2029d6 @balupton Prepped for docpad
balupton authored
183 ### Server
1bfb7fe @balupton More initial
balupton authored
184
47d182a @balupton 0.3. Generation and server are going
balupton authored
185 * Serve the generated static website
186 * Support dynamic pages which won't be generated statically (not yet done)
187 * Add NowPad support for interface (not yet done)
188 * Add user management (not yet done)
189 * Add revision history (not yet done)
190 * Add deployment options (not yet done)
1bfb7fe @balupton More initial
balupton authored
191
192
a2029d6 @balupton Prepped for docpad
balupton authored
193 ## History
1bfb7fe @balupton More initial
balupton authored
194
e7c7d32 @balupton 0.5. Pretty big clean
balupton authored
195 - v0.5 May 9, 2011
196 - Pretty big clean
197
198 - v0.4 May 9, 2011
199 - The CLI is now working as documented
200
47d182a @balupton 0.3. Generation and server are going
balupton authored
201 - v0.3 May 7, 2011
202 - Got the generation and server going
203
a2029d6 @balupton Prepped for docpad
balupton authored
204 - v0.2 March 24, 2011
205 - Prototyping with DisenchantCH
1bfb7fe @balupton More initial
balupton authored
206
a2029d6 @balupton Prepped for docpad
balupton authored
207 - v0.1 March 16, 2011
208 - Initial Commit with Bergie
1bfb7fe @balupton More initial
balupton authored
209
210
a2029d6 @balupton Prepped for docpad
balupton authored
211 ## License
1bfb7fe @balupton More initial
balupton authored
212
a2029d6 @balupton Prepped for docpad
balupton authored
213 Licensed under the [MIT License](http://creativecommons.org/licenses/MIT/)
214 Copyright 2011 [Benjamin Arthur Lupton](http://balupton.com)
Something went wrong with that request. Please try again.