Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 311 lines (195 sloc) 6.67 kb
1ea3366 @winton First commit
authored
1 Stasis
2 ======
4ab38af @winton [gem_template] First commit
authored
3
a2b7e5d @winton README
authored
4 Stasis is a dynamic framework for static sites.
37bbac2 @winton README
authored
5
55010da @winton Revert "Removing Travis CI for now (builds fail but specs pass locally u...
authored
6 [![Build Status](https://secure.travis-ci.org/winton/stasis.png)](http://travis-ci.org/winton/stasis)
7
0292263 @winton README, removing after filter
authored
8 Install
1ea3366 @winton First commit
authored
9 -------
10
a7cad8a @winton Updating README, gemspec fixes
authored
11 Install via [RubyGems](http://rubygems.org/pages/download):
1ea3366 @winton First commit
authored
12
d16d9eb @winton More work on web site
authored
13 <!-- language:console -->
14
15 $ gem install stasis
16
a7cad8a @winton Updating README, gemspec fixes
authored
17 Example
18 -------
d16d9eb @winton More work on web site
authored
19
a880da8 @winton More work on web site
authored
20 At its most essential, Stasis takes a directory tree with [supported template files](#supported_markup_languages) and renders them.
21
d16d9eb @winton More work on web site
authored
22 Example directory structure:
23
24 <!-- language:console -->
1ea3366 @winton First commit
authored
25
0292263 @winton README, removing after filter
authored
26 project/
27 index.html.haml
a7cad8a @winton Updating README, gemspec fixes
authored
28 images/
29 image.png
1ea3366 @winton First commit
authored
30
a880da8 @winton More work on web site
authored
31 Run `stasis`:
d16d9eb @winton More work on web site
authored
32
a880da8 @winton More work on web site
authored
33 <!-- highlight:stasis language:console -->
1ea3366 @winton First commit
authored
34
37bbac2 @winton README
authored
35 $ cd project
36 $ stasis
1ea3366 @winton First commit
authored
37
a880da8 @winton More work on web site
authored
38 Stasis creates a `public` directory:
d16d9eb @winton More work on web site
authored
39
a880da8 @winton More work on web site
authored
40 <!-- highlight:public/ language:console -->
1ea3366 @winton First commit
authored
41
0292263 @winton README, removing after filter
authored
42 project/
a880da8 @winton More work on web site
authored
43 index.html.haml
a7cad8a @winton Updating README, gemspec fixes
authored
44 images/
45 image.png
0292263 @winton README, removing after filter
authored
46 public/
47 index.html
a7cad8a @winton Updating README, gemspec fixes
authored
48 images/
49 image.png
c66b35b @winton More work
authored
50
fa956a6 @winton Changes
authored
51 `index.html.haml` becomes `public/index.html`.
c66b35b @winton More work
authored
52
a7cad8a @winton Updating README, gemspec fixes
authored
53 Unrecognized extensions are copied as-is (`image.png`).
1ea3366 @winton First commit
authored
54
55 Controllers
56 -----------
57
a7cad8a @winton Updating README, gemspec fixes
authored
58 Controllers contain Ruby code that executes once before all templates render.
1ea3366 @winton First commit
authored
59
a880da8 @winton More work on web site
authored
60 Example directory structure:
61
62 <!-- highlight:controller.rb language:console -->
d16d9eb @winton More work on web site
authored
63
0292263 @winton README, removing after filter
authored
64 project/
65 controller.rb
66 index.html.haml
a7cad8a @winton Updating README, gemspec fixes
authored
67 styles/
0292263 @winton README, removing after filter
authored
68 controller.rb
a7cad8a @winton Updating README, gemspec fixes
authored
69 style.css.sass
70
71
72 You may have a controller at any directory level.
6a8dd75 @winton Before all working
authored
73
d16d9eb @winton More work on web site
authored
74 Before
75 ------
6a8dd75 @winton Before all working
authored
76
1c95b1c @winton Lots of improvements to controller plugin scoping, README
authored
77 Use `before` blocks within `controller.rb` to execute code before a template renders.
a880da8 @winton More work on web site
authored
78
79 `controller.rb`:
f50ec06 @winton README
authored
80
0292263 @winton README, removing after filter
authored
81 before 'index.html.haml' do
82 @something = true
83 end
f50ec06 @winton README
authored
84
a880da8 @winton More work on web site
authored
85 `@something` is now available to the `index.html.haml` template.
37bbac2 @winton README
authored
86
a880da8 @winton More work on web site
authored
87 The `before` method can take any number of paths and/or regular expressions:
88
a7cad8a @winton Updating README, gemspec fixes
authored
89 before 'index.html.haml', /.*html\.erb/ do
a880da8 @winton More work on web site
authored
90 @something = true
91 end
f50ec06 @winton README
authored
92
0292263 @winton README, removing after filter
authored
93 Layouts
94 -------
1ea3366 @winton First commit
authored
95
a880da8 @winton More work on web site
authored
96 `layout.html.haml`:
c66b35b @winton More work
authored
97
0292263 @winton README, removing after filter
authored
98 %html
99 %body= yield
100
9e7c985 @winton Anchor smooth scrolling, github badge
authored
101 In `controller.rb`, set the default layout:
0292263 @winton README, removing after filter
authored
102
103 layout 'layout.html.haml'
1ea3366 @winton First commit
authored
104
25ea4e2 @winton README, bin file working, `before` controller method accepts multiple pa...
authored
105 Set the layout for a particular template:
1ea3366 @winton First commit
authored
106
0292263 @winton README, removing after filter
authored
107 layout 'index.html.haml' => 'layout.html.haml'
1ea3366 @winton First commit
authored
108
a880da8 @winton More work on web site
authored
109 Use a regular expression:
1ea3366 @winton First commit
authored
110
a880da8 @winton More work on web site
authored
111 layout /.*html.haml/ => 'layout.html.haml'
1ea3366 @winton First commit
authored
112
a880da8 @winton More work on web site
authored
113 Set the layout from a `before` block:
1ea3366 @winton First commit
authored
114
0292263 @winton README, removing after filter
authored
115 before 'index.html.haml' do
116 layout 'layout.html.haml'
f50ec06 @winton README
authored
117 end
1ea3366 @winton First commit
authored
118
d16d9eb @winton More work on web site
authored
119 Render
120 ------
0292263 @winton README, removing after filter
authored
121
d16d9eb @winton More work on web site
authored
122 Within a template:
0292263 @winton README, removing after filter
authored
123
124 %html
125 %body= render '_partial.html.haml'
6a8dd75 @winton Before all working
authored
126
d16d9eb @winton More work on web site
authored
127 Within a `before` block:
0292263 @winton README, removing after filter
authored
128
129 before 'index.html.haml' do
130 @partial = render '_partial.html.haml'
6a8dd75 @winton Before all working
authored
131 end
132
d16d9eb @winton More work on web site
authored
133 Text:
1ea3366 @winton First commit
authored
134
0292263 @winton README, removing after filter
authored
135 render :text => 'Hello'
1ea3366 @winton First commit
authored
136
d16d9eb @winton More work on web site
authored
137 Local variables:
1ea3366 @winton First commit
authored
138
0292263 @winton README, removing after filter
authored
139 render 'index.html.haml', :locals => { :x => true }
1ea3366 @winton First commit
authored
140
d16d9eb @winton More work on web site
authored
141 Include a block for the template to `yield` to:
1ea3366 @winton First commit
authored
142
0292263 @winton README, removing after filter
authored
143 render 'index.html.haml' { 'Hello' }
6a8dd75 @winton Before all working
authored
144
0292263 @winton README, removing after filter
authored
145 Instead
146 -------
6a8dd75 @winton Before all working
authored
147
25ea4e2 @winton README, bin file working, `before` controller method accepts multiple pa...
authored
148 The `instead` method changes the output of the template being rendered:
6a8dd75 @winton Before all working
authored
149
0292263 @winton README, removing after filter
authored
150 before 'index.html.haml' do
151 instead render('subdirectory/index.html.haml')
1ea3366 @winton First commit
authored
152 end
153
f50ec06 @winton README
authored
154 Helpers
155 -------
1ea3366 @winton First commit
authored
156
a880da8 @winton More work on web site
authored
157 `controller.rb`:
1ea3366 @winton First commit
authored
158
f50ec06 @winton README
authored
159 helpers do
0292263 @winton README, removing after filter
authored
160 def say_hello
161 'Hello'
f50ec06 @winton README
authored
162 end
1ea3366 @winton First commit
authored
163 end
164
a880da8 @winton More work on web site
authored
165 The `say_hello` method is now available to all `before` blocks and templates.
166
167 Ignore
168 ------
169
9e7c985 @winton Anchor smooth scrolling, github badge
authored
170 Use the `ignore` method in `controller.rb` to ignore certain paths.
a880da8 @winton More work on web site
authored
171
172 Ignore filenames with an underscore at the beginning:
173
69f9ca9 @winton Adding options to Stasis.new and making server response simpler
authored
174 ignore /\/_.*/
a880da8 @winton More work on web site
authored
175
c66b35b @winton More work
authored
176 Priority
177 --------
178
9e7c985 @winton Anchor smooth scrolling, github badge
authored
179 Use the `priority` method in `controller.rb` to change the file process order.
c66b35b @winton More work
authored
180
1c95b1c @winton Lots of improvements to controller plugin scoping, README
authored
181 Copy `.txt` files before rendering the `index.html.erb` template:
c66b35b @winton More work
authored
182
a880da8 @winton More work on web site
authored
183 priority /.*txt/ => 2, 'index.html.erb' => 1
c66b35b @winton More work
authored
184
a880da8 @winton More work on web site
authored
185 The default priority is `0` for all files.
c66b35b @winton More work
authored
186
1c95b1c @winton Lots of improvements to controller plugin scoping, README
authored
187 Usage
188 -----
189
190 ### Command Line
191
192 Always execute the `stasis` command in the root directory of your project.
193
fa956a6 @winton Changes
authored
194 Development mode (auto-regenerate on save):
1c95b1c @winton Lots of improvements to controller plugin scoping, README
authored
195
fa956a6 @winton Changes
authored
196 <!-- highlight:-d language:console -->
1c95b1c @winton Lots of improvements to controller plugin scoping, README
authored
197
fa956a6 @winton Changes
authored
198 $ stasis -d
1ea3366 @winton First commit
authored
199
3c59b45 @winton Instructions for web server in dev mode
authored
200 Specify a port to start an HTTP server:
201
202 <!-- highlight:-d language:console -->
203
204 $ stasis -d 3000
205
fa956a6 @winton Changes
authored
206 Only render specific files or directories:
d16d9eb @winton More work on web site
authored
207
fa956a6 @winton Changes
authored
208 <!-- highlight:-o language:console -->
1c95b1c @winton Lots of improvements to controller plugin scoping, README
authored
209
fa956a6 @winton Changes
authored
210 $ stasis -o index.html.haml,subdirectory
22ff326 @winton Adding ability to change destination of rendered files
authored
211
212 Change the public (destination) directory:
213
214 <!-- highlight:-o language:console -->
215
216 $ stasis -p ../public
fa956a6 @winton Changes
authored
217
a7cad8a @winton Updating README, gemspec fixes
authored
218 ### Ruby Library
1c95b1c @winton Lots of improvements to controller plugin scoping, README
authored
219
818c0d9 @AquaGeek Minor spelling fix
AquaGeek authored
220 Instantiate a `Stasis` object:
1c95b1c @winton Lots of improvements to controller plugin scoping, README
authored
221
222 stasis = Stasis.new('/path/to/project/root')
223
22ff326 @winton Adding ability to change destination of rendered files
authored
224 Optionally specify a destination directory:
225
226 stasis = Stasis.new('/project', '/html')
227
1c95b1c @winton Lots of improvements to controller plugin scoping, README
authored
228 Render all templates:
229
230 stasis.render
231
232 Render a specific template or directory:
233
234 stasis.render('index.html.haml', 'subdirectory')
235
236 More
237 ----
d16d9eb @winton More work on web site
authored
238
239 ### Supported Markup Languages
240
241 Stasis uses [Tilt](https://github.com/rtomayko/tilt) to support the following template engines:
242
243 <!-- language:console -->
244
245 ENGINE FILE EXTENSIONS
a7cad8a @winton Updating README, gemspec fixes
authored
246 -------------------------- -----------------------
d16d9eb @winton More work on web site
authored
247 ERB .erb, .rhtml
248 Interpolated String .str
249 Erubis .erb, .rhtml, .erubis
250 Haml .haml
251 Sass .sass
252 Scss .scss
253 Less CSS .less
254 Builder .builder
255 Liquid .liquid
256 RDiscount .markdown, .mkd, .md
257 Redcarpet .markdown, .mkd, .md
258 BlueCloth .markdown, .mkd, .md
259 Kramdown .markdown, .mkd, .md
260 Maruku .markdown, .mkd, .md
261 RedCloth .textile
262 RDoc .rdoc
263 Radius .radius
264 Markaby .mab
265 Nokogiri .nokogiri
266 CoffeeScript .coffee
a7cad8a @winton Updating README, gemspec fixes
authored
267 Creole (Wiki markup) .wiki, .creole
268 WikiCloth (Wiki markup) .wiki, .mediawiki, .mw
fa956a6 @winton Changes
authored
269 Yajl .yajl
270
271 ### Server Mode
272
273 Stasis can run as a server that uses [redis](http://redis.io) to wait for render jobs.
274
275 Stasis server that uses redis on port 6379:
276
277 <!-- highlight:-s language:console -->
278
048eccb @winton Stasis::Server mostly working
authored
279 $ stasis -s localhost:6379/0
fa956a6 @winton Changes
authored
280
281 Push to the server (in Ruby):
282
283 Stasis::Server.push(
284 # Paths to render
285 :paths => [ "index.html.haml", "subdirectory" ],
286
95fdaee @winton Adding params option to Stasis#render and Stasis::Server.push
authored
287 # Made available to views as `params`
288 :params => {},
289
ed6b6f1 @winton Stasis::Server really working now
authored
290 # Redis address
291 :redis => "localhost:6379/0",
fa956a6 @winton Changes
authored
292
293 # Return rendered templates (false by default)
bd2229a @winton README
authored
294 :return => false,
fa956a6 @winton Changes
authored
295
296 # Block until templates generate (false by default)
bd2229a @winton README
authored
297 :wait => false,
298
299 # Write to the filesystem (true by default)
df4b536 @winton Adding :force option to Stasis::Server.push
authored
300 :write => true,
301
302 # Cache ttl for returned templates (nil by default)
303 :ttl => nil,
304
305 # Force write even if cached (false by default)
306 :force => false
a7cad8a @winton Updating README, gemspec fixes
authored
307 )
308
309 ### This Web Site
310
311 [Take a look at the Stasis project](https://github.com/winton/stasis/tree/master/site) that automatically generated this web site from the project [README](https://github.com/winton/stasis/blob/master/README.md).
Something went wrong with that request. Please try again.