Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 283 lines (173 sloc) 11.879 kb
68e6557 @balupton readme updates
balupton authored
1 # DocPad. Intuitive web development. <a href="http://flattr.com/thing/344188/balupton-on-Flattr" target="_blank">
f3551b3 @balupton Updated flattr button, as apparently the old link wasn't working.
balupton authored
2 <img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this project" title="Flattr this project" border="0" /></a>
2bcbdcc @balupton Added Flattr button
balupton authored
3
fad131d @balupton readme update
balupton authored
4 Initially web development was pretty easy, you just wrote a bunch of files and you got your website. These days, it's a lot more complicated than that. Things like databases, synchronisation, legacy frameworks and languages all slow the entire process down into a painful crawl. _It doesn't have to be like that._
d14f380 @balupton 0.6. Moved to CoffeeScript. Removed highlight.js
balupton authored
5
a79c0f5 @balupton v2.0.2. Now uses coffee-script@1.1.3. Changed some UK english to US e…
balupton authored
6 DocPad takes that good ol' simple approach of writing files and wraps it with the best modern innovations, providing an awesome intuitive, liberating and empowering solution for HTML5 web design & development.
1bfb7fe @balupton More initial
balupton authored
7
0f1654a @balupton more readme updates
balupton authored
8 At its core DocPad is a language agnostic document management system. This means you write your website as documents, in whatever language you wish, and DocPad will handle the compiling, templates and layouts for you. For static documents it will generate static files, for dynamic documents it'll re-render them on each request. You can utilise DocPad by itself, or use it as a module your own custom system. It's pretty cool, and well worth checking out. We love it.
3185802 @balupton New readme copy. Let me know what you think :-)
balupton authored
9
62476f1 @balupton Muwahahhaha. Added support for Ruby, ERuby, and PHP. WOOHOOO.
balupton authored
10
11
12
ea9377f @balupton Cleaned up the readme a bit, tried to make it more concise.
balupton authored
13 ## When would using DocPad be ideal?
62476f1 @balupton Muwahahhaha. Added support for Ruby, ERuby, and PHP. WOOHOOO.
balupton authored
14
0f1654a @balupton more readme updates
balupton authored
15 - for learning and implementing new languages and web technologies into real-world applications
16 - DocPad's ability to run a potential infinite amount of languages is amazing, and as you are always working with a real website you're never forced to re-implement anything into another system.
17
18 - for rapid prototyping of new interfaces which need to facilate changes quickly
19 - The ability to get up and running as quickly as possible with DocPad really helps here, along with its support for pre-precessors you can quickly move about your codebase and rejig things when things need to change - without having to rewrite any architecture.
62476f1 @balupton Muwahahhaha. Added support for Ruby, ERuby, and PHP. WOOHOOO.
balupton authored
20
ea9377f @balupton Cleaned up the readme a bit, tried to make it more concise.
balupton authored
21 - for frontend prototypes which will be handed over to the backend developers for implementation
22 - Often to gain layouts, templating, and pre-precessor support we'll have to implement a web framework, a templating engine, and code a custom build script for each of our pre-precessors that we use. This takes a lot of uncessary time, and complicates things during handover to the backend developers who then need to learn the tools that you've used. Using DocPad we abstract all that difficulty and handle it beautifully, allowing you to just focus on the files you want to write, and we'll provide you with the layout engine, templating engine, and pre-precessor support you need. When it comes to handover, the backend developers will have your source files, as well as the compiled files allowing them to use whichever is easiest for them.
23
24 - for simple websites like blogs, launch pages, etc
25 - DocPad's static site generation abilities are great for this, and with DocPad's built-in support for dynamic documents we can also cater for the odd search page, enquiry form or twitter steam
26
27 - for thick client-side web applications
28 - Combining DocPad's pre-precessor support and static site generation is amazing for developing thick client applications, as you can utilise the latest pre-precessors at any time, allowing you to focus on the problem, instead of how to implement the problem
29
30
0f1654a @balupton more readme updates
balupton authored
31
32
33 ## What features does it support?
34
35 - it's language agnostic, allowing you to write your documents in any language you wish, we already support over 10 languages (listed a few sections later)
36 - it will watch your source files for changes, and ensure your website is up to date automatically
37 - you'll get growl notifications every time we regenerate your website
38 - you can mix and match renderers, allowing you to combine languages e.g. eco and markdown with `file.html.md.eco`
39 - you can write both static and dynamic documents
40 - for static documents a static output file will be generated
41 - for dynamic documents they will be re-rendered on each request
42 - it provides a liquid layout engine allowing you to wrap a document in an infinite amount of layouts
43 - it provides an in-memory nosql database which you can query inside your documents or inside your app
44 - you can use DocPad as a module inside a bigger application, allowing you to utilise DocPad's generation abilities but do the heavy lifting in your own application
45 - it exposes the built-in [express.js](http://expressjs.com/) web server so you can extend it with your own routes and business logic
46 - it runs great on Linux, OSX, and Windows, as well as Node.js 0.4 and 0.6
47 - it provides automatic version checking letting you know when it's time to update
48 - you can add new features to DocPad easily and simply with its powerful plugin infrastucture
49 - it provides you with pre-made skeletons which can bootstrap your next project
50
51
52
68e6557 @balupton readme updates
balupton authored
53 ## What languages does it support?
54
0f1654a @balupton more readme updates
balupton authored
55
68e6557 @balupton readme updates
balupton authored
56 ### Markups
57
58 - [Markdown](http://daringfireball.net/projects/markdown/basics) to HTML `.html.md|markdown`
59 - [Eco](https://github.com/sstephenson/eco) to anything `.anything.eco`
60 - [CoffeeKup](http://coffeekup.org/) to anything `.anything.ck|coffeekup|coffee` and HTML to CoffeeKup `.ck|coffeekup|coffee.html`
61 - [Jade](http://jade-lang.com/) to anything `.anything.jade` and HTML to Jade `.jade.html`
62 - [HAML](http://haml-lang.com/) to anything `.anything.haml`
63 - [Ruby](http://www.ruby-lang.org/) to anything `.anything.rb|ruby`
64 - [ERuby](http://en.wikipedia.org/wiki/ERuby) to anything `.anything.erb`
65 - [PHP](http://php.net/) to anything `.anything.php`
66
0f1654a @balupton more readme updates
balupton authored
67
68e6557 @balupton readme updates
balupton authored
68 ### Styles
69
70 - [Stylus](http://learnboost.github.com/stylus/) to CSS `.css.styl|stylus`
71 - [LessCSS](http://lesscss.org/) to CSS `.css.less`
72 - [SASS](http://sass-lang.com/) to CSS `.css.sass|scss`
73
0f1654a @balupton more readme updates
balupton authored
74
68e6557 @balupton readme updates
balupton authored
75 ### Scripts
76
77 - [CoffeeScript](http://coffeescript.org/) to JavaScript `.js.coffee` and JavaScript to CoffeeScript `.coffee.js`
78 - [Roy](http://roy.brianmckenna.org/) to JavaScript `.js.roy`
79 - [Move](http://movelang.org/) to JavaScript `.js.move`
80
0f1654a @balupton more readme updates
balupton authored
81
68e6557 @balupton readme updates
balupton authored
82 ### Parsers
83
84 - [YAML](https://github.com/visionmedia/js-yaml) with `--- yaml` (default)
85 - [CoffeeScript](http://jashkenas.github.com/coffee-script/) with `--- coffee`
86
0f1654a @balupton more readme updates
balupton authored
87 _Parsers are used inside the meta data areas of your content_
88
89
ea9377f @balupton Cleaned up the readme a bit, tried to make it more concise.
balupton authored
90
91 ## How does it work?
1bfb7fe @balupton More initial
balupton authored
92
bc10ae7 @balupton Typos
balupton authored
93 1. Say you were to create the following website structure:
dc382c2 @balupton Update to readme
balupton authored
94
c240804 @balupton Typos
balupton authored
95 > - myWebsite
dc382c2 @balupton Update to readme
balupton authored
96 - src
36befea @balupton Should now support multiple skeletons
balupton authored
97 - documents
dc382c2 @balupton Update to readme
balupton authored
98 - layouts
10f11da @balupton readme update
balupton authored
99 - public
1bfb7fe @balupton More initial
balupton authored
100
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
101 1. And you were to create the following files:
1bfb7fe @balupton More initial
balupton authored
102
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
103 - A layout at `src/layouts/default.html.eco`, which contains
dc382c2 @balupton Update to readme
balupton authored
104
105 ``` html
106 <html>
cfc7c3c @balupton fixed code examples in readme - thanks @delapouite for the heads up
balupton authored
107 <head><title><%=@document.title%></title></head>
dc382c2 @balupton Update to readme
balupton authored
108 <body>
973497f @balupton Removed initial planning notes concieved with Sven. Fixed typos in re…
balupton authored
109 <%-@content%>
dc382c2 @balupton Update to readme
balupton authored
110 </body>
111 </html>
112 ```
1bfb7fe @balupton More initial
balupton authored
113
918fca5 @balupton readme updates
balupton authored
114 - And another layout at `src/layouts/post.html.eco`, which contains:
dc382c2 @balupton Update to readme
balupton authored
115
116 ``` html
117 ---
118 layout: default
119 ---
cfc7c3c @balupton fixed code examples in readme - thanks @delapouite for the heads up
balupton authored
120 <h1><%=@document.title%></h1>
973497f @balupton Removed initial planning notes concieved with Sven. Fixed typos in re…
balupton authored
121 <div><%-@content%></div>
dc382c2 @balupton Update to readme
balupton authored
122 ```
123
1b9ebb5 @balupton Twitter bootstrap skeleton now default. Deleted server.coffee. Added …
balupton authored
124 - And a document at `src/documents/posts/hello.html.md`, which contains:
dc382c2 @balupton Update to readme
balupton authored
125
126 ``` html
127 ---
128 layout: post
129 title: Hello World!
130 ---
131 Hello **World!**
132 ```
133
62476f1 @balupton Muwahahhaha. Added support for Ruby, ERuby, and PHP. WOOHOOO.
balupton authored
134 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
135
136 ``` html
137 <html>
138 <head><title>Hello World!</title></head>
139 <body>
140 <h1>Hello World!</h1>
141 <div>Hello <strong>World!</strong></div>
142 </body>
143 </html>
144 ```
145
10f11da @balupton readme update
balupton authored
146 1. 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`
dc382c2 @balupton Update to readme
balupton authored
147
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
148 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
149
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
150 1. Cool, now what was with the `<%=...%>` and `<%-...%>` parts which were substituted away?
dc382c2 @balupton Update to readme
balupton authored
151
5437d91 @balupton Fixed some bad text in the readme
balupton authored
152 - 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
153
154 ``` html
cfc7c3c @balupton fixed code examples in readme - thanks @delapouite for the heads up
balupton authored
155 <% for document in @documents: %>
156 <% if document.url.indexOf('/posts') is 0: %>
157 <a href="<%= document.url %>"><%= document.title %></a><br/>
dc382c2 @balupton Update to readme
balupton authored
158 <% end %>
36befea @balupton Should now support multiple skeletons
balupton authored
159 <% end %>
160 ```
230068c @balupton Renamed parsers to renderers. Updated readme to reflect latest changes
balupton authored
161
162 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
163
27a2ddb @balupton readme updates
balupton authored
164 - 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
165
0f1654a @balupton more readme updates
balupton authored
166 1. Great thanks! I think I will give it a go right now!
13bfb35 @balupton Now uses Benjamin Lupton's watchr library for file watching, has supp…
balupton authored
167
168
169
c1b7c7c @balupton Minor
balupton authored
170 ## Installing
dc382c2 @balupton Update to readme
balupton authored
171
d770781 @balupton Cleaned
balupton authored
172 1. [Install Node.js](https://github.com/balupton/node/wiki/Installing-Node.js)
a63518b @balupton Updated installation instructions
balupton authored
173
6607847 @balupton Updated installation details and changelog to mention buildr dependen…
balupton authored
174 1. Install dependencies
d14f380 @balupton 0.6. Moved to CoffeeScript. Removed highlight.js
balupton authored
175
a79c0f5 @balupton v2.0.2. Now uses coffee-script@1.1.3. Changed some UK english to US e…
balupton authored
176 npm install -g coffee-script
d14f380 @balupton 0.6. Moved to CoffeeScript. Removed highlight.js
balupton authored
177
6864fed @balupton whoops, still had the install mongodb requirement in the readme
balupton authored
178 1. Install DocPad
a63518b @balupton Updated installation instructions
balupton authored
179
e45112a @balupton Updated coffee-script install version
balupton authored
180 npm install -g docpad
1bfb7fe @balupton More initial
balupton authored
181
13bfb35 @balupton Now uses Benjamin Lupton's watchr library for file watching, has supp…
balupton authored
182 1. If you also want growl notifications (OSX), then install [the growl command line tool here](http://growl.cachefly.net/GrowlNotify-1.3.zip)
183
8542d82 @balupton v2.6.0. Released fixes for #115. Updated for balupton -> bevry move. …
balupton authored
184 _Getting errors? [Try troubleshooting](https://github.com/bevry/docpad/wiki/Troubleshooting)_
f0df79f @balupton added note about installing the cutting edge version
balupton authored
185
13bfb35 @balupton Now uses Benjamin Lupton's watchr library for file watching, has supp…
balupton authored
186
187
0f1654a @balupton more readme updates
balupton authored
188
dc382c2 @balupton Update to readme
balupton authored
189 ## Using
1bfb7fe @balupton More initial
balupton authored
190
7290284 @balupton updated readme usage instructions
balupton authored
191 - Firstly, make a directory for your new website and cd into it
ed7565c @balupton updated readme usage instructions
balupton authored
192
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
193 ``` bash
194 mkdir my-new-website
195 cd my-new-website
196 ```
ed7565c @balupton updated readme usage instructions
balupton authored
197
ff95cce @balupton updated readme usage instructions
balupton authored
198 - To get started, simply run the following - it will run all the other commands at once
47d182a @balupton 0.3. Generation and server are going
balupton authored
199
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
200 ``` bash
201 docpad run
202 ```
47d182a @balupton 0.3. Generation and server are going
balupton authored
203
ff95cce @balupton updated readme usage instructions
balupton authored
204 - To generate a basic website structure in the current working directory if we don't already have one
1bfb7fe @balupton More initial
balupton authored
205
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
206 ``` bash
207 docpad scaffold
208 ```
1bfb7fe @balupton More initial
balupton authored
209
a2029d6 @balupton Prepped for docpad
balupton authored
210 - To regenerate the rendered website
1bfb7fe @balupton More initial
balupton authored
211
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
212 ``` bash
213 docpad generate
214 ```
1bfb7fe @balupton More initial
balupton authored
215
a2029d6 @balupton Prepped for docpad
balupton authored
216 - To regenerate the rendered website automatically whenever we make a change to a file
1bfb7fe @balupton More initial
balupton authored
217
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
218 ``` bash
219 docpad watch
220 ```
1bfb7fe @balupton More initial
balupton authored
221
62476f1 @balupton Muwahahhaha. Added support for Ruby, ERuby, and PHP. WOOHOOO.
balupton authored
222 - To run the DocPad server which allows you to access the generated website in a web browser
1bfb7fe @balupton More initial
balupton authored
223
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
224 ``` bash
225 docpad server
226 ```
d770781 @balupton Cleaned
balupton authored
227
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
228 - To render an individual file with DocPad programatically (will output to stdout)
d770781 @balupton Cleaned
balupton authored
229
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
230 ``` bash
231 docpad render filePath
232 ```
1bfb7fe @balupton More initial
balupton authored
233
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
234 E.g. To render a markdown file and save the result to an output file, we would use:
f2e5873 @balupton 0.7. Now supports multiple docpad instances
balupton authored
235
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
236 ``` bash
237 docpad render inputMarkdownFile.html.md > outputMarkdownFile.html
238 ```
d14f380 @balupton 0.6. Moved to CoffeeScript. Removed highlight.js
balupton authored
239
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
240 - To render stdin with DocPad programatically (will output to stdout)
e7c7d32 @balupton 0.5. Pretty big clean
balupton authored
241
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
242 ``` bash
5e5b571 @balupton minor readme changes
balupton authored
243 echo $content | docpad render sampleFileNameWithExtensions
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
244 ```
e7c7d32 @balupton 0.5. Pretty big clean
balupton authored
245
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
246 E.g. To render passed markdown content and save the result to a file, we would use:
247
248 ``` bash
5e5b571 @balupton minor readme changes
balupton authored
249 echo "**awesome**" | docpad render input.html.md > output.html
25b3e9b @balupton Added the ability to render file programmatically via the command line
balupton authored
250 ```
47d182a @balupton 0.3. Generation and server are going
balupton authored
251
1bfb7fe @balupton More initial
balupton authored
252
8542d82 @balupton v2.6.0. Released fixes for #115. Updated for balupton -> bevry move. …
balupton authored
253 _Getting errors? [Try troubleshooting](https://github.com/bevry/docpad/wiki/Troubleshooting)_
1bfb7fe @balupton More initial
balupton authored
254
255
d777dde @balupton readme updates
balupton authored
256
257
0f1654a @balupton more readme updates
balupton authored
258 ## Thanks
f380ea9 @balupton Updated readme. Updated changelog. Updated credits.
balupton authored
259
0f1654a @balupton more readme updates
balupton authored
260 DocPad is doing great these days, thanks to people like you! You can check out [a bunch of websites already using it here](https://github.com/bevry/docpad/wiki/Showcase), and [discover the awesomely handsome crew behind the community here](https://github.com/bevry/docpad/wiki/Users). Ocassionally we also hold [events and competitions](https://github.com/bevry/docpad/wiki/Events) where you can learn more about DocPad, hack with others together, and win some cool stuff! Nifty.
4f9194a @balupton v2.5.0. Properly fixed #111. Split html2jade out of the jade plugin, …
balupton authored
261
0f1654a @balupton more readme updates
balupton authored
262 On that note, DocPad is awesomely extensible. You can [download other people's plugins](https://github.com/bevry/docpad/wiki/Extensions) and use them in real quick, or even [write your own in matters of minutes.](https://github.com/bevry/docpad/wiki/Extending)
f380ea9 @balupton Updated readme. Updated changelog. Updated credits.
balupton authored
263
0f1654a @balupton more readme updates
balupton authored
264 [Best yet, definitely check out the entire wiki, as this has just been a small taste of it's awesomeness, and there is plenty awesomness left to be discovered.](https://github.com/bevry/docpad/wiki)
f380ea9 @balupton Updated readme. Updated changelog. Updated credits.
balupton authored
265
0f1654a @balupton more readme updates
balupton authored
266 Thanks! DocPad loves you!!!
c056c60 @balupton New plugin structure. More cleaning.
balupton authored
267
58510b7 @balupton v2.2.0. Updated readme. Fixed bug with dynamic pages mime type.
balupton authored
268
f380ea9 @balupton Updated readme. Updated changelog. Updated credits.
balupton authored
269
d777dde @balupton readme updates
balupton authored
270
4cfe5f2 @balupton Added note about History.md inside readme
balupton authored
271 ## History
272
62476f1 @balupton Muwahahhaha. Added support for Ruby, ERuby, and PHP. WOOHOOO.
balupton authored
273 You can discover the history inside the [History.md](https://github.com/bevry/docpad/blob/master/History.md#files) file
d777dde @balupton readme updates
balupton authored
274
275
0f1654a @balupton more readme updates
balupton authored
276
277
a2029d6 @balupton Prepped for docpad
balupton authored
278 ## License
1bfb7fe @balupton More initial
balupton authored
279
ce1737d @balupton Added support for Hogan. Added support for the newer version of Cater…
balupton authored
280 Licensed under the [MIT License](http://creativecommons.org/licenses/MIT/)
1da5d3c @balupton v2.6.1. Updated kitchensink.docpad repo url
balupton authored
281 <br/>Copyright &copy; 2012 [Bevry Pty Ltd](http://bevry.me)
282 <br/>Copyright &copy; 2011 [Benjamin Lupton](http://balupton.com)
Something went wrong with that request. Please try again.