source: project/wiki/eggref/4/hyde @ 27180

Last change on this file since 27180 was 27180, checked in by Moritz Heidkamp, 7 years ago

hyde: Update documentation

File size: 16.3 KB
Line 
1[[tags: egg]]
2
3== Hyde
4
5[[toc:]]
6
7=== Description
8
9A static website compiler
10
11=== Author
12
13[[/users/moritz-heidkamp|Moritz Heidkamp]]
14
15=== Requirements
16
17
18Requires the [[environments]], [[sxml-transforms]], [[matchable]],
19[[scss]], [[filepath]], [[spiffy]], [[doctype]], [[colorize]], [[multidoc]],
20[[defstruct]], [[atom]] and [[rfc3339]] extensions.
21
22Since there is no native
23[[http://daringfireball.net/projects/markdown/|Markdown]] parser
24available in Chicken at the moment, you'll also have to have a
25{{markdown}} program available in your {{PATH}} to use Markdown in
26your pages.
27
28=== Documentation
29
30Hyde is a program for compiling static websites from a variety of
31input files. It is basically a Schemey clone of programs such as
32[[http://webby.rubyforge.org/|Webby]] and, particularly name-wise,
33[[http://jekyllrb.com/|Jekyll]]. Note that there is
34[[http://ringce.com/hyde|another project named Hyde]] which is similar
35in purpose but written in Python.
36
37Hyde can be run through the {{hyde}} executable contained in this egg.
38
39A website is, in Hyde's sense, a directory containing at least a
40{{hyde.scm}} file. This file is evaluated before any command and can
41be used to set parameters or define helper functions. It should also
42contain a directory of source files (unless the {{(source-dir)}}
43parameter points somewhere outside the current directory). Invoking
44the compilation process will recursively traverse {{(source-dir)}} and
45do one of the following things for each file it finds:
46
47* If the file's extension is unknown to Hyde, copy the file to the
48same relative path within {{(output-dir)}} unchanged.
49
50* If the file's extension is known to Hyde, translate its contents,
51possibly wrap the result in one or more layouts and write it to the
52same relative path within {{(output-dir)}}, possibly changing its
53extension.
54
55
56In the latter case, the translator used is determined by the source
57file's extension (see [[#translators|translators]] for a list of
58available translators). Before translation, the file is {{(read)}},
59i.e. the first s-expression in the file is read from it. This
60s-expression must be an alist (or a null list) holding arbitrary
61page-vars which are made available within the page's as well as the
62layouts' evaluation environment. This can be used to set a page title,
63for example. The rest of the file is considered the page's body and is
64left to be translated by the translator.
65
66=== Example
67
68Hyde's functionality is probably best understood by an example
69session. Let's start by initializing a site:
70
71    $ mkdir cool-site
72    $ cd cool-site
73    $ hyde init
74    creating layouts
75    creating src
76    creating out
77    creating hyde.scm
78    creating layouts/default.sxml
79   
80We now have a basic site structure. The next step would probably be to
81add some pages, so let's start by creating an index page in wiki
82(i.e. svnwiki) format:
83
84    $ hyde new wiki index
85    src/index.wiki
86    $ cat src/index.wiki
87    ((title . "index"))
88   
89As you can see, Hyde created the source file and inserted the file
90name as a page-var called {{title}}, too (actually it's the other way
91around: the argument for {{hyde new}} is the title and Hyde transforms
92this into a suitable file name, i.e. it removes special chars and
93substitutes spaces with dashes). This is handy as the default layout
94uses this to fill the {{<title>}} tag in the resulting HTML document:
95
96    $ cat layouts/default.sxml
97    ()
98    `((xhtml-1.0-strict)
99      (html
100       (head
101        (title ,($ 'title)))
102       (body
103        (h1 ,($ 'title))
104        (inject ,contents))))
105
106As we learn from that example, page-vars can be referred to through
107the {{$}} function which is made available by Hyde in the environment
108which SXML (as well as SCSS and Atom) pages are evaluated in. Also
109note the {{inject}} transformation rule which allows injection of
110unescaped HTML into the document. Finally, the variable {{contents}}
111contains the translated page contents (see
112[[#available-bindings-during-page-evaluation|Available Bindings During
113Page Evaluation]]).
114
115Let's add a little content to our page and compile the site:
116
117    $ echo 'Hey, welcome to my cool site!' >> src/index.wiki
118    $ hyde
119    cleaning output directory
120    preparing compilation
121    compiling pages
122    * index.wiki -> index.html
123
124    $ cat out/index.html
125    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
126    <html>
127    <head>
128    <title>index</title></head>
129    <body>
130    <h1>index</h1>
131    <p>Hey, welcome to my cool site!</p>
132    </body></html>
133
134As you can see, Hyde renamed {{index.wiki}} to {{index.html}}. This
135can be changed through the {{default-extension}} parameter or by
136adding a page-var {{ext}} to the page:
137
138    $ cat src/index.wiki
139    ((title . "index")
140     (ext   . "xml"))
141    Hey, welcome to my cool site!
142
143    $ hyde           
144    cleaning output directory
145    preparing compilation
146    compiling pages
147    * index.wiki -> index.xml
148
149=== Available Options
150
151The {{hyde}} executable understands the following options:
152
153; {{-e HYDE_ENV_NAME}} : Sets the hyde environment to execute the command in (see [[#available-commands|Available Commands]] for which commands respect this option and [[#define-hyde-environment|define-hyde-environment]] on how to define environments).
154
155
156=== Available Commands
157
158The {{hyde}} executable understands the following commands:
159
160; {{hyde init}} : Initializes a site in the current directory.
161; {{hyde new <page-type> [<title> ...]}} : Creates a new page with the given page type and title. The page's filename will be inferred from the given title by downcasing it and replacing spaces with dashes.
162; {{hyde serve}} : Serves the current site with [[spiffy]], (re-)compiling the requested page on each request (useful for development). This command respects the {{-e}} option.
163; {{hyde build [<prefix> ...]}} : Builds the current site. If prefixes are given then only paths having those prefixes will be built. This command respects the {{-e}} option.
164; {{hyde}} : Compiles the current site. This command respects the {{-e}} option.
165
166=== Configuration Parameters
167
168The following parameters are available to configure Hyde's
169behavior. They are usually set in a site's {{hyde.scm}}.
170
171
172<parameter>(source-dir [dir])</parameter>
173
174The directory in which source pages are kept. Default: {{"src"}}
175
176
177<parameter>(layouts-dir [dir])</parameter>
178
179The directory in which layouts are kept. Default: {{"layouts"}}
180
181
182<parameter>(output-dir [dir])</parameter>
183
184The directory compilation results will be written to. Default:
185{{"out"}}
186
187
188<parameter>(default-layouts [layouts])</parameter>
189
190A list of default layouts which are applied when no other is
191specified. Default: {{'("default.sxml")}}
192
193
194<parameter>(clean-before-build [bool])</parameter>
195
196Indicates whether to purge the {{output-dir}} before compilation or
197not. Default: {{#t}}
198
199
200<parameter>(excluded-paths [regexes])</parameter>
201
202A list of regular expressions matching paths which are to be ignored
203when compiling. Default: {{`(,(irregex (seq "~" eos)))}}
204
205
206<parameter>(default-extension [extension])</parameter>
207
208The file extension to use for compiled pages which don't explicitly
209specify an extension. Default: {{"html"}}
210
211
212<parameter>(default-page-vars [page-vars])</parameter>
213
214An alist which maps either (ir)regexps or procedures to
215page-vars. Each page has its {{page-source-path}} matched against the
216(ir)regexps or is passed to the procedure. If it matches or returns
217non-{{#f}}, the respective page-vars are appended to the page's local
218page-vars, i.e. local page-vars have precedence over them.  Default: {{'()}}
219
220Example:
221
222The following {{default-page-vars}} would set the {{layouts}} page-var
223to {{("page.sxml" "default.sxml")}} for all {{.sxml}} pages with the
224relative path prefix {{pages/}} and the page-vars {{tags}} to
225{{(awful)}} for all pages containing the word "cool":
226
227<enscript language="scheme">
228(default-page-vars `(((seq bos "pages/" (+ any) ".sxml" eos)
229                      (layouts "page.sxml" "default.sxml"))
230
231                     (,(lambda (page)
232                        (irregex-search "cool" (read-page page)))
233                      (tags awful))))
234</enscript>
235
236
237<parameter>(page-eval-env [env])</parameter>
238
239The environment for evaluating SXML and SCSS files. Default:
240{{(environment-copy (interaction-environment) #t)}}
241
242
243<parameter>(translators [translators-alist])</parameter>
244
245An alist of source language translators indexed by file extensions. Default:
246
247    `(("sxml" . ,hyde#translate/sxml)
248      ("scss" . ,hyde#translate/scss)
249      ("md"   . ,hyde#translate/markdown)
250      ("wiki" . ,hyde#translate/svnwiki)
251      ("sw"   . ,hyde#translate/svnwiki))
252
253Additionally, {{("atom" . ,hyde-atom#translate/atom)}} can be made
254available by loading the {{hyde-atom}} extension from the site's
255{{hyde.scm}}.
256
257
258<parameter>(uri-path-prefix [path])</parameter>
259
260A string that is prepended to all pages' {{page-path}}. Default: {{""}}.
261
262
263<parameter>(shortcut-links [shortcuts])</parameter>
264
265An alist of shortcut names (symbols) mapping to URI templates
266containing {{format}} placeholders. These shortcuts can be used with the
267following page translators:
268
269; svnwiki : The {{[[link]]}} syntax is extended to allow shortcuts to be used by prefixing the path with the shortcut name and a colon, for example: {{[[foo:something]]}} will use the {{foo}} shortcut and substitute the first placeholder with {{"something"}}.
270; sxml : The transformation rule {{shortcut}} can be used to expand a shortcut name into a URI, for example: {{(a (@ (href (shortcut foo "something"))))}}.
271
272This feature has been added in version 0.12.
273
274
275<parameter>(ignore-page? [predicate])</parameter>
276
277`predicate` is a procedure accepting a page; when it returns `#t` that
278page will not be compiled to an output file (it can still be accessed
279through `pages` though).
280
281This parameter has been added in version 0.16.
282
283
284=== Helpers
285
286These procedures and macros are mainly intended for use in the
287{{hyde.scm}} or in extension modules.
288
289
290<syntax>(define-hyde-environment name body ...)</syntax>
291
292Defines an environment {{name}}. The {{body}} expressions are only
293evaluated when {{hyde}} is executed with {{-e [name]}}. This is useful
294to set different parameters for different scenarios or deployment
295locations. If no {{-e}} option is set, the {{default}} environment is
296used. Just {{(define-hyde-environment default ...)}} to override
297it. See [[#available-commands|Available Commands]] for which commands
298respect environments.
299
300
301<syntax>(make-external-translator name)</syntax>
302
303Creates a procedure that reads from {{(current-input-port)}} and
304writes to the standard input of the program {{name}}
305linewise. Afterwards, its standard output is read back and written to
306{{(current-output-port)}}, also linewise. It can be used to create
307page translators for external programs, e.g. the markdown translator
308included in Hyde is defined like this:
309
310<enscript language="scheme">
311(define translate/markdown (make-external-translator (markdown-program)))
312(translators (cons (list "md" translate/markdown) (translators)))
313</enscript>
314
315
316<procedure>(pathify string)</procedure>
317
318Turn `string` into a URL friendly path name.
319
320Example:
321
322<enscript language="scheme">
323(pathify "This is \"something\" nice.") ; => "this-is-something-nice"
324</enscript>
325
326Exported since version 0.16.
327
328
329<constant>sxml-conversion-rules</constant>
330
331The set of SXML conversion rules used for translating `sxml` pages.
332
333Exported since version 0.15.
334
335
336=== Available Bindings During Page Evaluation
337
338In pages which are evaluated as Scheme (currently SXML, SCSS and Atom
339pages), the following bindings are available:
340
341
342<procedure>($ page-var #!optional page)</procedure>
343
344Returns the value of {{page-var}} (a symbol identifiying the page-var)
345or {{#f}} if no {{page-var}} of that name exists. By giving the
346optional {{page}} argument, refer to that page's page-vars instead of
347the current page's.
348
349
350<parameter>pages</parameter>
351
352An alist of all available pages indexed by their source file names
353relative to {{(source-dir)}}. The values are {{page}} records.
354
355This used to be a constant up until version 0.13.
356
357
358<procedure>(current-page)</procedure>
359
360Returns the current page's record.
361
362
363<procedure>(page-path #!optional (page (current-page)))</procedure>
364
365Returns the given {{page}}'s absolute URI path.
366
367
368<procedure>(page-source-path #!optional (page (current-page)))</procedure>
369
370Returns the given {{page}}'s source path relative to {{(source-dir)}}.
371
372
373<procedure>(page-vars #!optional (page (current-page)))</procedure>
374
375Returns the given {{page}}'s page-vars as an alist.
376
377
378<procedure>(page-type #!optional (page (current-page)))</procedure>
379
380Returns the given {{page}}'s type which is one of the following symbols:
381
382; dynamic : a page which is handled by one of Hyde's page translators
383; static : a page which is just copied to {{(output-dir)}}
384; directory : a directory
385
386
387<procedure>(read-page page #!rest layouts)</procedure>
388
389Returns the given {{page}}'s contents, possibly wrapped in the given
390{{layouts}}. {{page}} may be either a {{page}} record or a path
391relative to {{(source-dir)}}. This procedure is useful to create
392aggregate pages. Note that it will translate the contents of dynamic
393{{page}}s even if they have not been compiled, yet. In this case, they
394will neither be wrapped in page-specific nor the default layouts, only
395the ones given in {{layouts}}.
396
397
398<constant>contents</constant>
399
400The translated contents of the current page. Only available in layouts.
401
402=== Change Log
403
404; 0.16 ; Add `hyde build` command. Allow link-shortcuts to be procedures. Extract `pathify`. Use `big-chicken` module environment when possible. Fix issue in `hyde serve` with trailing slashes on paths (thanks John J Foerch for the patch). Add `ignore-page?`. Fix escaping issue in colorize-code (thanks Peter Bex for the patch). Add a link with relation `alternate` to the atom feed emitted by `hyde-atom`.
405; 0.15 ; Add `hyde-atom` module for convenient generation of atom feeds from pages. Export {{sxml-conversion-rules}}
406; 0.14 : Some compatibility changes. Depend on Spiffy >= 4.9.
407; 0.13 : Update to scss 0.3. Make {{pages}} a parameter in {{page-eval-env}}.
408; 0.12 : Add {{link-shortcuts}}.
409; 0.11 : Change {{default-page-vars}} irregex keys to match against {{page-source-path}} instead of {{page-path}}. Add environments. Add {{uri-path-prefix}}.
410; 0.10 : Add colorize support to svnwiki pages. Implement more powerful {{default-page-vars}}. Add {{make-external-translator}} (thanks to Christian Kellermann for the patch). Only recompile requested pages instead of the whole site with {{hyde serve}}.
411; 0.9 : Print usage for unknown commands (thanks to Christian Kellermann). Add current-page binding and make it the default argument for all page record field accessors.
412; 0.8 : Add svnwiki and atom page translators. Make pages a proper type. Allow creation of aggregate pages through {{read-page}}. Drop {{sxml-shortcuts}} from {{sxml-conversion-rules}}.
413
414
415=== To Do
416
417* document layout nesting
418* change default extension to be an alist mapping source extensions to
419  target extensions
420
421=== License
422
423  Copyright (c) 2010-2012, Moritz Heidkamp
424  All rights reserved.
425 
426  Redistribution and use in source and binary forms, with or without
427  modification, are permitted provided that the following conditions are
428  met:
429 
430  Redistributions of source code must retain the above copyright
431  notice, this list of conditions and the following disclaimer.
432 
433  Redistributions in binary form must reproduce the above copyright
434  notice, this list of conditions and the following disclaimer in the
435  documentation and/or other materials provided with the distribution.
436 
437  Neither the name of the author nor the names of its contributors may
438  be used to endorse or promote products derived from this software
439  without specific prior written permission.
440 
441  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
442  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
443  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
444  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
445  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
446  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
447  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
448  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
449  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
450  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
451  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
452  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.