Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 217 lines (145 sloc) 7.027 kb
dc382c2 @balupton Update to readme
balupton authored
1 # DocPad: It's Like Jekyll.
1bfb7fe @balupton More initial
balupton authored
2
d14f380 @balupton 0.6. Moved to CoffeeScript. Removed highlight.js
balupton authored
3 DocPad (like Jekyll) is a static website generator, unlike Jekyll it's written in CoffeeScript+Node.js instead of Ruby, and also allows the template engine complete access to the document model. This means you have unlimited power as a CMS and the simplicity of a notepad.
4
1bfb7fe @balupton More initial
balupton authored
5
a2029d6 @balupton Prepped for docpad
balupton authored
6 ## Huh?
1bfb7fe @balupton More initial
balupton authored
7
bc10ae7 @balupton Typos
balupton authored
8 1. Say you were to create the following website structure:
dc382c2 @balupton Update to readme
balupton authored
9
c240804 @balupton Typos
balupton authored
10 > - myWebsite
dc382c2 @balupton Update to readme
balupton authored
11 - src
36befea @balupton Should now support multiple skeletons
balupton authored
12 - documents
13 - files
dc382c2 @balupton Update to readme
balupton authored
14 - layouts
1bfb7fe @balupton More initial
balupton authored
15
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
16 1. And you were to create the following files:
1bfb7fe @balupton More initial
balupton authored
17
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
18 - A layout at `src/layouts/default.html.eco`, which contains
dc382c2 @balupton Update to readme
balupton authored
19
20 ``` html
21 <html>
973497f @balupton Removed initial planning notes concieved with Sven. Fixed typos in readm...
balupton authored
22 <head><title><%=@Document.title%></title></head>
dc382c2 @balupton Update to readme
balupton authored
23 <body>
973497f @balupton Removed initial planning notes concieved with Sven. Fixed typos in readm...
balupton authored
24 <%-@content%>
dc382c2 @balupton Update to readme
balupton authored
25 </body>
26 </html>
27 ```
1bfb7fe @balupton More initial
balupton authored
28
918fca5 @balupton readme updates
balupton authored
29 - And another layout at `src/layouts/post.html.eco`, which contains:
dc382c2 @balupton Update to readme
balupton authored
30
31 ``` html
32 ---
33 layout: default
34 ---
973497f @balupton Removed initial planning notes concieved with Sven. Fixed typos in readm...
balupton authored
35 <h1><%=@Document.title%></h1>
36 <div><%-@content%></div>
dc382c2 @balupton Update to readme
balupton authored
37 ```
38
1b9ebb5 @balupton Twitter bootstrap skeleton now default. Deleted server.coffee. Added not...
balupton authored
39 - And a document at `src/documents/posts/hello.html.md`, which contains:
dc382c2 @balupton Update to readme
balupton authored
40
41 ``` html
42 ---
43 layout: post
44 title: Hello World!
45 ---
46 Hello **World!**
47 ```
48
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
49 1. Then when you generate your website with docpad you will get a html file at `out/posts/hello.html`, which contains:
dc382c2 @balupton Update to readme
balupton authored
50
51 ``` html
52 <html>
53 <head><title>Hello World!</title></head>
54 <body>
55 <h1>Hello World!</h1>
56 <div>Hello <strong>World!</strong></div>
57 </body>
58 </html>
59 ```
60
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
61 1. And any files that you have in `src/files` will be copied to the `out` directory. E.g. `src/files/styles/style.css` -> `out/styles/style.css`
dc382c2 @balupton Update to readme
balupton authored
62
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
63 1. Allowing you to easily generate a website which only changes (and automatically updates) when a document changes (which when you think about it; is the majority of websites)
dc382c2 @balupton Update to readme
balupton authored
64
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
65 1. Cool, now what was with the `<%=...%>` and `<%-...%>` parts which were substituted away?
dc382c2 @balupton Update to readme
balupton authored
66
5437d91 @balupton Fixed some bad text in the readme
balupton authored
67 - This is possible because we parse the documents and layouts through a template rendering engine. The template rendering engine used in this example was [Eco](https://github.com/sstephenson/eco) (hence the `.eco` extensions of the layouts). Templating engines allows you to do some pretty nifty things, in fact we could display all the titles and links of our posts with the following:
36befea @balupton Should now support multiple skeletons
balupton authored
68
69 ``` html
70 <% for Document in @Documents: %>
71 <% if Document.url.indexOf('/posts') is 0: %>
72 <a href="<%= Document.url %>"><%= Document.title %></a><br/>
dc382c2 @balupton Update to readme
balupton authored
73 <% end %>
36befea @balupton Should now support multiple skeletons
balupton authored
74 <% end %>
75 ```
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
76
77 1. Cool that makes sense... now how did `Hello **World!**` in our document get converted into `Hello <strong>World!</strong>`?
dc382c2 @balupton Update to readme
balupton authored
78
27a2ddb @balupton readme updates
balupton authored
79 - That was possible as that file was a [Markdown](http://daringfireball.net/projects/markdown/basics) file (hence the `.md` extension it had). Markdown is fantastic for working with text based documents, as it really allows you to focus in on your content instead of the syntax for formatting the document!
1bfb7fe @balupton More initial
balupton authored
80
81
c1b7c7c @balupton Minor
balupton authored
82 ## Installing
dc382c2 @balupton Update to readme
balupton authored
83
d770781 @balupton Cleaned
balupton authored
84 1. [Install Node.js](https://github.com/balupton/node/wiki/Installing-Node.js)
a63518b @balupton Updated installation instructions
balupton authored
85
275e7d0 @balupton 0.9.20. DocPad server now supports get/post/... by using server.all for ...
balupton authored
86 1. Install [CoffeeScript](http://jashkenas.github.com/coffee-script/)
d14f380 @balupton 0.6. Moved to CoffeeScript. Removed highlight.js
balupton authored
87
88 npm -g install coffee-script
89
6864fed @balupton whoops, still had the install mongodb requirement in the readme
balupton authored
90 1. Install DocPad
a63518b @balupton Updated installation instructions
balupton authored
91
d98d3c5 @balupton The docpad cli now works
balupton authored
92 npm -g install docpad
1bfb7fe @balupton More initial
balupton authored
93
5d4667f @balupton updated readme
balupton authored
94 1. _or... install the cutting edge version_
f0df79f @balupton added note about installing the cutting edge version
balupton authored
95
96 git clone git://github.com/balupton/docpad.git
97 cd docpad
607f484 @balupton Updated readme to reflect the latest
balupton authored
98 git checkout v1.0
d77709c @balupton updated readme
balupton authored
99 npm install
100 git submodule init
101 git submodule update
f0df79f @balupton added note about installing the cutting edge version
balupton authored
102 npm link
103
104
105
dc382c2 @balupton Update to readme
balupton authored
106 ## Using
1bfb7fe @balupton More initial
balupton authored
107
47d182a @balupton 0.3. Generation and server are going
balupton authored
108 - To generate the rendered website, watch the files for changes, and run the docpad server
109
25b04ba @balupton Cleaned the CLI
balupton authored
110 docpad run
47d182a @balupton 0.3. Generation and server are going
balupton authored
111
a2029d6 @balupton Prepped for docpad
balupton authored
112 - To generate a basic website structure in the current working directory
1bfb7fe @balupton More initial
balupton authored
113
25b04ba @balupton Cleaned the CLI
balupton authored
114 docpad scaffold
1bfb7fe @balupton More initial
balupton authored
115
a2029d6 @balupton Prepped for docpad
balupton authored
116 - To regenerate the rendered website
1bfb7fe @balupton More initial
balupton authored
117
a2029d6 @balupton Prepped for docpad
balupton authored
118 docpad generate
1bfb7fe @balupton More initial
balupton authored
119
a2029d6 @balupton Prepped for docpad
balupton authored
120 - To regenerate the rendered website automatically whenever we make a change to a file
1bfb7fe @balupton More initial
balupton authored
121
a2029d6 @balupton Prepped for docpad
balupton authored
122 docpad watch
1bfb7fe @balupton More initial
balupton authored
123
2914630 @balupton Typos
balupton authored
124 - To run the docpad server which allows you to access the generated website in a web browser
1bfb7fe @balupton More initial
balupton authored
125
a2029d6 @balupton Prepped for docpad
balupton authored
126 docpad server
1bfb7fe @balupton More initial
balupton authored
127
128
c1b7c7c @balupton Minor
balupton authored
129 ## Created With
130
131 ### General
132
133 * [Node.js](http://nodejs.org) - Server Side Javascript
3fff2bd @balupton 0.9. Dropped MongoDB/Mongoose for Query-Engine.
balupton authored
134 * [Express.js](http://expressjs.com) - The "Server" in Server Side Javascript
135 * [Query-Engine](https://github.com/balupton/query-engine.npm) - The MongoDB Query-Engine without the Database
607f484 @balupton Updated readme to reflect the latest
balupton authored
136 * [CoffeeScript](http://jashkenas.github.com/coffee-script) - JavaScript made easy
137 * [Caterpillar](https://github.com/balupton/caterpillar.npm) - Logging made easy
138 * [Bal-Util](https://github.com/balupton/bal-util.npm) - Node.js made easy
139 * [YAML](https://github.com/visionmedia/js-yaml) - Data made easy
140 * [Commander.js](https://github.com/visionmedia/commander.js) - Console apps made easy
c1b7c7c @balupton Minor
balupton authored
141
a73b7af @balupton 0.11-beta. Introduced the concept of renderers. Still needs some cleanin...
balupton authored
142 ### Renderers
c1b7c7c @balupton Minor
balupton authored
143
607f484 @balupton Updated readme to reflect the latest
balupton authored
144 * [Markdown](http://daringfireball.net/projects/markdown/basics) - markup made easy
145 * [Eco](https://github.com/sstephenson/eco) - Templating made easy
146 * [CoffeeKup](http://coffeekup.org/) - HTML as CoffeeScript
147 * [Jade](http://jade-lang.com/) - HTML made easy
148 * [HAML](http://haml-lang.com/) - Markup haiku
149
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
150
151 ### Extensions
152
153 DocPad is also quite extensible, it's easy to add support for new renderers and even add funky new functionality ontop of docpad! [Check out what others are making](https://github.com/balupton/docpad/wiki/Extensions), or [learn to make your own extensions here.](https://github.com/balupton/docpad/wiki/Extending)
c1b7c7c @balupton Minor
balupton authored
154
155
d770781 @balupton Cleaned
balupton authored
156 ## Learning
157
2914630 @balupton Typos
balupton authored
158 [To learn more about DocPad (including using and extending it) visit its wiki here](https://github.com/balupton/docpad/wiki)
d770781 @balupton Cleaned
balupton authored
159
160
a2029d6 @balupton Prepped for docpad
balupton authored
161 ## History
1bfb7fe @balupton More initial
balupton authored
162
607f484 @balupton Updated readme to reflect the latest
balupton authored
163 - v1.0-beta September 20, 2011
164 - v0.x users need to follow this upgrade guide [to be done]
a73b7af @balupton 0.11-beta. Introduced the concept of renderers. Still needs some cleanin...
balupton authored
165 - The concept of template engines and markup languages have been merged into the concept of renderers
607f484 @balupton Updated readme to reflect the latest
balupton authored
166 - Added [CoffeeKup](http://coffeekup.org/) renderer
167 - Including support for coffee <-> js, and coffeekup <-> html
168 - Added a [Commander.js](https://github.com/visionmedia/commander.js) based CLI thanks to [~eldios](https://github.com/eldios)
169 - TODO:
170 - Clean urls plugin could do with some work
171 - Documentation of the new document extension handling needs to be done
172 - Documentation on plugin handling needs to be done
173 - Do the upgrade guide
174
a73b7af @balupton 0.11-beta. Introduced the concept of renderers. Still needs some cleanin...
balupton authored
175
a987de2 @balupton Updated readme
balupton authored
176 - v0.10 September 14, 2011
177 - Plugin infrastructure
178 - Better logging through [Caterpillar](https://github.com/balupton/caterpillar.npm)
2b60f0d @balupton 0.10.0. Plugin infrastructure. Better logging. Haml support. Fixed jade.
balupton authored
179 - Added [Haml](https://github.com/visionmedia/haml.js) support
180 - Fixed [Jade](https://github.com/visionmedia/jade) support
a987de2 @balupton Updated readme
balupton authored
181
3fff2bd @balupton 0.9. Dropped MongoDB/Mongoose for Query-Engine.
balupton authored
182 - v0.9 July 6, 2011
183 - No longer uses MongoDB/Mongoose! We now use [Query-Engine](https://github.com/balupton/query-engine.npm) which doesn't need any database server :)
e08f4df @balupton 0.9.5. Now supports clean urls
balupton authored
184 - Watching files now working even better
185 - Now supports clean urls :)
3fff2bd @balupton 0.9. Dropped MongoDB/Mongoose for Query-Engine.
balupton authored
186
fc7bb1b @balupton 0.8. Now supports multiple skeletons
balupton authored
187 - v0.8 May 23, 2011
188 - Now supports mutliple skeletons
189 - Structure changes
190
f2e5873 @balupton 0.7. Now supports multiple docpad instances
balupton authored
191 - v0.7 May 20, 2011
192 - Now supports multiple docpad instances
193
d14f380 @balupton 0.6. Moved to CoffeeScript. Removed highlight.js
balupton authored
194 - v0.6 May 12, 2011
195 - Moved to CoffeeScript
196 - Removed highlight.js (should be a plugin or client-side feature)
197
e7c7d32 @balupton 0.5. Pretty big clean
balupton authored
198 - v0.5 May 9, 2011
199 - Pretty big clean
200
201 - v0.4 May 9, 2011
202 - The CLI is now working as documented
203
47d182a @balupton 0.3. Generation and server are going
balupton authored
204 - v0.3 May 7, 2011
205 - Got the generation and server going
206
a2029d6 @balupton Prepped for docpad
balupton authored
207 - v0.2 March 24, 2011
ee0f5f5 @balupton Updates for new bal-util
balupton authored
208 - Prototyping with [disenchant](https://github.com/disenchant)
1bfb7fe @balupton More initial
balupton authored
209
a2029d6 @balupton Prepped for docpad
balupton authored
210 - v0.1 March 16, 2011
ee0f5f5 @balupton Updates for new bal-util
balupton authored
211 - Initial commit with [bergie](https://github.com/bergie)
1bfb7fe @balupton More initial
balupton authored
212
213
a2029d6 @balupton Prepped for docpad
balupton authored
214 ## License
1bfb7fe @balupton More initial
balupton authored
215
a2029d6 @balupton Prepped for docpad
balupton authored
216 Licensed under the [MIT License](http://creativecommons.org/licenses/MIT/)
217 Copyright 2011 [Benjamin Arthur Lupton](http://balupton.com)
Something went wrong with that request. Please try again.