chickadee » hyde

Hyde

Description

A static website compilery

Author

Moritz Heidkamp

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/4/hyde

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Requirements

Although there is a native Markdown parser for Chicken these days (called Lowdown) due to historical reasons you'll have to have a markdown program available in your PATH to use Markdown in your Hyde pages for the time being. Alternatively you can define a custom page translator using Lowdown (see translators).

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. Note that there is another project named Hyde which is similar in purpose but written in Python.

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:

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.

Applying css to a website is done by using scss or regular css. Documentation for the syntax used in scss can be found in scss.

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 wiki (i.e. svnwiki) format:

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

As you can see, Hyde created the source file and inserted the file name as a page-var called title, too (actually it's the other way around: the argument for hyde new is the title and Hyde transforms this into a suitable file name, i.e. it removes special chars and substitutes spaces with dashes). 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 learn from that example, page-vars can be referred to through the $ function which is made available by Hyde in the environment which SXML (as well as SCSS and Atom) 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.wiki
   $ hyde
   cleaning output directory
   preparing compilation
   compiling pages
   * index.wiki -> 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.wiki to index.html. This can be changed through the default-extension parameter or by adding a page-var ext to the page:

   $ cat src/index.wiki
   ((title . "index")
    (ext   . "xml"))
   Hey, welcome to my cool site!
   $ hyde            
   cleaning output directory
   preparing compilation
   compiling pages
   * index.wiki -> index.xml

Available Options

The hyde executable understands the following options:

-e HYDE_ENV_NAME
Sets the hyde environment to execute the command in (see Available Commands for which commands respect this option and define-hyde-environment on how to define environments).

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. The page's filename will be inferred from the given title by downcasing it and replacing spaces with dashes.
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.
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.
hyde
Compiles the current site. This command respects the -e option.

Configuration Parameters

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

source-dir #!optional dirparameter

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

layouts-dir #!optional dirparameter

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

output-dir #!optional dirparameter

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

default-layouts #!optional layoutsparameter

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

clean-before-build #!optional boolparameter

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

excluded-paths #!optional regexesparameter

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

default-extension #!optional extensionparameter

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

default-page-vars #!optional page-varsparameter

An alist which maps either (ir)regexps or procedures to page-vars. Each page has its page-source-path matched against the (ir)regexps or is passed to the procedure. If it matches or returns non-#f, the respective page-vars are appended to the page's local page-vars, i.e. local page-vars have precedence over them. Default: '()

Example:

The following default-page-vars would set the layouts page-var to ("page.sxml" "default.sxml") for all .sxml pages with the relative path prefix pages/ and the page-vars tags to (awful) for all pages containing the word "cool":

(default-page-vars `(((seq bos "pages/" (+ any) ".sxml" eos)
                      (layouts "page.sxml" "default.sxml"))

                     (,(lambda (page)
                        (irregex-search "cool" (read-page page)))
                      (tags awful))))
page-eval-env #!optional envparameter

The environment for evaluating SXML and SCSS pages. It needs to be an environment created via the hyde-page-eval-env module which is a (mostly) drop-in replacement for the deprecated environments egg. Note that the top-level environment is always used as a fallback for lookup.

uri-path-prefix #!optional pathparameter

A string that is prepended to all pages' page-path. Default: "".

An alist of shortcut names (symbols) mapping to URI templates containing format placeholders. These shortcuts can be used with the following page translators:

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".
sxml
The transformation rule shortcut can be used to expand a shortcut name into a URI, for example: (a (@ (href (shortcut foo "something")))).

This feature has been added in version 0.12.

ignore-page? #!optional predicateparameter

predicate is a procedure accepting a page; when it returns #t that page will not be compiled to an output file (it can still be accessed through pages though).

This parameter has been added in version 0.16.

ignore-page? #!optional predicateparameter

Page accessors

pagesparameter

An alist of all available pages indexed by their source file names relative to (source-dir). The values are page records. Note that it is only bound during site compilation, i.e. not yet when hyde.scm is loaded.

This used to be a constant up until version 0.13 and was only available in the page-eval-env up until 0.20.0.

page-by-path pathprocedure

Looks up a page by its target path (i.e. page-path), which can be given as a string or a list of strings representing the path components.

current-pageprocedure

Returns the current page's record. Only bound during compilation.

page-path pageprocedure

Returns the given page's absolute URI path.

page-source-path pageprocedure

Returns the given page's source path relative to (source-dir).

page-vars pageprocedure

Returns the given page's page-vars as an alist.

page-type pageprocedure

Returns the given page's type which is one of the following symbols:

dynamic
a page which is handled by one of Hyde's page translators
static
a page which is just copied to (output-dir)
directory
a directory
read-page page #!rest layoutsprocedure

Returns the given page's contents, possibly wrapped in the given layouts. page may be either a page record or a path relative to (source-dir). This procedure is useful to create aggregate pages. Note that it will translate the contents of dynamic pages even if they have not been compiled, yet. In this case, they will neither be wrapped in page-specific nor the default layouts, only the ones given in layouts.

Translators

A translator is a zero-argument procedure which is expected to read the contents of a Hyde page from (current-input-port) and write its translation to (current-output-port). For example, the SXML translator shipped with Hyde reads s-expressions from (current-input-port), evaluates them in (page-eval-env), applies sxml-conversion-rules and finally writes the result rendered as HTML to (current-output-port). Note The page-vars preamble has already been read and interpreted at the point a translator is called. The page being translated is available via (current-page).

translate-sxmlprocedure
translate-scssprocedure
translate-markdownprocedure
translate-svnwikiprocedure

Translators for SXML, SCSS, Markdown and svnwiki formatted pages. See translators parameter for which files extensions they are mapped to.

translators #!optional translators-alistparameter

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

    `(("sxml" ,translate-sxml) 
      ("scss" ,translate-scss (ext . css) (layouts))
      ("md"   ,translate-markdown)
      ("wiki" ,translate-svnwiki)
      ("sw"   ,translate-svnwiki))

Additionally, `("atom" ,translate-atom (ext . atom) (layouts)) can be made available by loading the (hyde atom) extension from your site's hyde.scm.

To use Lowdown for Markdown pages you need to define a custom page translator in your site's hyde.scm like this:

(use lowdown)
(translators (cons (list "md" markdown->html) (translators)))
make-external-translator program-name #!optional argsprocedure

Creates a procedure that reads from (current-input-port) and writes to the standard input of the external program program-name (either a string or a thunk returning a string). Optionally a thunk can be passed for args which needs to return a list of arguments for the program. The program's standard output is read back and written to (current-output-port). It can be used to create page translators for external programs, e.g. the markdown translator included in Hyde is defined like this:

(define translate-markdown (make-external-translator markdown-program))
(translators (cons (list "md" translate-markdown) (translators)))

Helpers

These procedures and macros are mainly intended for use in the hyde.scm or in extension modules.

(define-hyde-environment name body ...)syntax

Defines an environment name. The body expressions are only evaluated when hyde is executed with -e [name]. This is useful to set different parameters for different scenarios or deployment locations. If no -e option is set, the default environment is used. Just (define-hyde-environment default ...) to override it. See Available Commands for which commands respect environments.

pathify stringprocedure

Turn string into a URL friendly path name.

Example:

(pathify "This is \"something\" nice.") ; => "this-is-something-nice"

Exported since version 0.16.

sxml-conversion-rulesconstant

The set of SXML conversion rules used for translating sxml pages.

Exported since version 0.15.

serve-page page path continueprocedure

Default handler for the hyde serve command which translates dynamic pages when requested by their target path and tries to serve index files for directories as defined via Spiffy's index-files parameter. Static files are handled by Spiffy's default handler.

See also page-serve-handler.

Available Bindings During Page Evaluation

In pages which are evaluated as Scheme (currently SXML, SCSS and Atom pages), the following bindings are available:

$ page-var #!optional pageprocedure

Returns the value of page-var (a symbol identifiying the page-var) or #f if no page-var of that name exists. By giving the optional page argument, refer to that page's page-vars instead of the current page's.

contentsconstant

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

Hooks

around-page-translateparameter

A procedure that is called for every page translation. It needs to accept the following arguments:

page
The page being translated
translate
A thunk which returns the translation result

The procedure needs to return the translation result. Default:

(lambda (page translate) (translate))

Available since version 0.21.0.

page-serve-handlerparameter

A procedure that is called for every request handled by hyde serve. It needs to accept the following arguments:

page
The requested page or #f if none was found for the requested path
path
The requested path represented as a list of strings
continue
A thunk to be called in case no response was sent

The procedure should either send a response (e.g. via Spiffy's send-response procedure) or call the continue thunk. The default is serve-page.

Available since version 0.21.0.

Version History

Version 3

Version 2

Version 0.21.0

Version 0.20.0

Version 0.16

Version 0.15

Version 0.14

Version 0.13

Version 0.12

Version 0.11

Version 0.10

Version 0.9

Version 0.8

To Do

License

 Copyright (c) 2010-2019, 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.

Contents »