Hyde (historical revision 18238) - The CHICKEN Scheme wiki

You are looking at historical revision 18238 of this page. It may differ significantly from its current revision.

Hyde

Requirements

Requires the environments, sxml-transforms, sxml-fu matchable, scss, filepath, spiffy, and doctype extensions.

Since there is no native Markdown parser available in Chicken at the moment, you'll also have to have a markdown program available in your PATH to use Markdown in your pages.

Documentation

Hyde is a program for compiling static websites from a variety of input files. It is basically a Schemey clone of programs such as Webby and, particularly name-wise, Jekyll.

Hyde can be run through the hyde executable contained in this egg.

A website is, in Hyde's sense, a directory containing at least a hyde.scm file. This file is evaluated before any command and can be used to set parameters or define helper functions. It should also contain a directory of source files (unless the source-dir parameter points somewhere outside the current directory). Invoking the compilation process will recursively traverse source-dir and do one of the following things for each file it finds:

If the file's extension is unknown to hyde, copy the file to the same relative path within output-dir unchanged.
If the file's extension is known to hyde, translate its contents, possibly wrap the result in one or more layouts and write it to the same relative path within output-dir, possibly changing its extension.

In the latter case, the translator used is determined by the source file's extension (see translators for a list of available translators). Before translation, the file is (read), i.e. the first s-expression in the file is read from it. This s-expression must be an alist (or a null list) holding arbitrary page-vars which are made available within the page's as well as the layouts' evaluation environment. This can be used to set a page title, for example. The rest of the file is considered the page's body and is left to be translated by the translator.

Example

Hyde's functionality is probably best understood by an example session. Let's start by initializing a site:

   $ mkdir cool-site
   $ cd cool-site 
   $ hyde init
   creating layouts
   creating src
   creating out
   creating hyde.scm
   creating layouts/default.sxml

We now have a basic site structure. The next step would probably be to add some pages, so let's start by creating an index page in markdown format:

   $ hyde new md index
   src/index.md
   $ cat src/index.md 
   ((title . "index"))

As you can see, hyde created the source file and inserted the file name as a page-var called title, too. This is handy as the default layout uses this to fill the <title> tag in the resulting HTML document:

   $ cat layouts/default.sxml 
   ()
   `((xhtml-1.0-strict)
     (html
      (head
(title ,($ 'title)))
      (body
(h1 ,($ 'title))
(inject ,contents))))

As we can lean from that example, page-vars can be referred to through the $ function which is made available by Hyde in the environment which SXML (ans SCSS) pages are evaluated in. Also note the inject transformation rule which allows injection of unescaped HTML into the document. Finally, the variable contents contains the translated page contents (see Available Bindings During Page Evaluation).

Let's add a little content to our page and compile the site:

   $ echo 'Hey, welcome to my cool site!' >> src/index.md
   $ hyde
   cleaning output directory
   preparing compilation
   compiling pages
   * index.md -> index.html

   $ cat out/index.html 
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   <html>
   <head>
   <title>index</title></head>
   <body>
   <h1>index</h1><p>Hey, welcome to my cool site!</p>
   </body></html>

As you can see, Hyde renamed index.md to index.html. This can be changed through the default-extension or by adding a page-var ext to the page:

   $ cat src/index.md
   ((title . "index")
    (ext   . "xml"))
   Hey, welcome to my cool site!

   $ hyde            
   cleaning output directory
   preparing compilation
   compiling pages
   * index.md -> index.xml

Available Commands

The hyde executable understands the following commands:

hyde init: Initializes a site in the current directory
hyde new <page-type> [<title> ...]: Creates a new page with the given page type and title
hyde serve: Serves the current site with spiffy, compiling the site on each request
hyde: Compiles the current site

Configuration Parameters

The following parameters are available to configure hyde's behavior. They are usually set in a site's hyde.scm.

source-dir

[parameter] (source-dir [dir])

The directory in which source pages are kept. Default: "src"

layouts-dir

[parameter] (layouts-dir [dir])

The directory in which layouts are kept. Default: "layouts"

output-dir

[parameter] (output-dir [dir])

The directory compilation results will be written to. Default: "out"

default-layouts

[parameter] (default-layouts [layouts])

A list of default layouts which are applied when no other is specified. Default: '("default.sxml")

clean-before-build

[parameter] (clean-before-build [bool])

Indicates whether to purge the output-dir before compilation or not. Default: #t

excluded-paths

[parameter] (excluded-paths [regexes])

A list of regular expressions matching paths which are to be ignored when compiling. Default: `((irregex (seq "~" eos)))

default-extension

[parameter] (default-extension [extension])

The file extension to use for compiled pages which don't explicitly specify an extension. Default: "html"

default-page-vars

[parameter] (default-page-vars [page-vars])

An alist of page-vars which are available by default. Default: '()

page-eval-env

[parameter] (page-eval-env [env])

The environment for evaluating SXML and SCSS files. Default: (environment-copy (interaction-environment) #t)

translators

[parameter] (translators [translators-alist])

An alist of source language translators indexed by file extensions. Default:

   `(("sxml" . ,hyde#translate/sxml) 
     ("scss" . ,hyde#translate/scss) 
     ("md"   . ,hyde#translate/markdown))

    <pages> ::= ((<relative-source-file-path> <absolute-uri-path> <page-vars>) ...)
    <relative-source-file-path> ::= the page file path relative to {{(source-dir)}}
    <absolute-uri-path> ::= the absolute URI path of the compiled page (i.e. the target file path relative to {{(output-dir)}} prefixed with {{"/"}})
    <page-vars> ::= an alist of page-vars for this page

[constant] contents

The translated contents of the current page. Only available in layouts.

To Do

document layout nesting
change default extension to be an alist mapping source extensions to target extensions

License

 Copyright (c) 2010, Moritz Heidkamp
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 Neither the name of the author nor the names of its contributors may
 be used to endorse or promote products derived from this software
 without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.