diff options
| -rw-r--r-- | doc/haunt.texi | 408 |
1 files changed, 395 insertions, 13 deletions
diff --git a/doc/haunt.texi b/doc/haunt.texi index a6db328..262b979 100644 --- a/doc/haunt.texi +++ b/doc/haunt.texi @@ -355,6 +355,7 @@ Automatically rebuild the site when source files change. * Readers:: Post interpreters. * Pages:: HTML/XML pages. * Assets:: Images, stylesheets, etc. +* Builders:: Web page builders. @end menu Haunt is a fully-programmable system composed of several Guile Scheme @@ -363,6 +364,10 @@ modules. This section documents the public API. @node Sites @section Sites +@example +(use-modules (haunt site)) +@end example + A site object defines all of the properties for a Haunt website: The site name, domain name, where blog posts are found, what post formats are understood, which procedures are used to build the site, where the @@ -370,38 +375,39 @@ output files are written to, etc. @deffn {Scheme Procedure} site [#:title "This Place is Haunted"] @ [#:domain "example.com"] [#:posts-directory "posts"] @ - [#:file-filter @var{default-file-filter}] @ + [#:file-filter @code{default-file-filter}] @ [#:build-directory "site"] [#:default-metadata '()] @ - [#:make-slug @var{post-slug}] [#:readers '()] @ + [#:make-slug @code{post-slug}] [#:readers '()] @ [#:builders '()] Create a new site object. All arguments are optional: -@table @code +@table @var -@item @var{title} +@item title The name of the site. -@item @var{posts-directory} +@item posts-directory The directory where posts are found. -@item @var{file-filter} -A predicate procedure that returns #f when a post file should be -ignored, and #f otherwise. Emacs temp files are ignored by default. +@item file-filter +A predicate procedure that returns @code{#f} when a post file should +be ignored, and @code{#t} otherwise. Emacs temporary files are +ignored by default. -@item @var{build-directory} +@item build-directory The directory that generated pages are stored in. -@item @var{default-metadata} +@item default-metadata An alist of arbitrary default metadata for posts whose keys are symbols. -@item @var{make-slug} +@item make-slug A procedure generating a file name slug from a post. -@item @var{readers} +@item readers A list of reader objects for processing posts. -@item @var{builders} +@item builders A list of procedures for building pages from posts. @end table @@ -447,15 +453,391 @@ Return the list of builder procedures for @var{site}. @node Posts @section Posts +@example +(use-modules (haunt post)) +@end example + +Posts represent the articles that are kept in a site's post directory +and written in a markup format that Haunt can +understand. @pxref{Readers}) for how files on disk can be transformed +into posts. + +@deffn {Scheme Procedure} make-post @var{file-name} @var{metadata} @var{sxml} +Create a new post object that represents the contents of the file +@var{file-name}. The body of the post, @var{sxml}, is represented as +an SXML tree (@pxref{SXML, SXML,, guile, GNU Guile Reference Manual}) +and the metadata is an association list (@pxref{Association Lists, +Association Lists,, guile, GNU Guile Reference Manual}) of arbitrary +key/value pairs. +@end deffn + +@deffn {Scheme Procedure} post? @var{object} +Return @code{#t} if @var{object} is a post. +@end deffn + +@deffn {Scheme Procedure} post-file-name @var{post} +Return the file name for @var{post}. +@end deffn + +@deffn {Scheme Procedure} post-metadata @var{post} +Return the metadata association list for @var{post}. +@end deffn + +@deffn {Scheme Procedure} post-sxml @var{post} +Return the SXML tree for @var{post}. +@end deffn + +@deffn {Scheme Procedure} post-ref @var{post} @var{key} +Return the metadata value corresponding to @var{key} within +@var{post}. +@end deffn + +@deffn {Scheme Procedure} post-slug @var{post} +Transform the title of @var{post} into a URL slug suitable for the +file name of a web page. +@end deffn + +@defvr {Scheme Variable} %default-date +The default date of a post when no other date is specified in the +metadata association list. +@end defvr + +@deffn {Scheme Procedure} post-data @var{post} +Return the date for @var{post}, or @code{%default-date} if no date is +specified. +@end deffn + +@deffn {Scheme Procedure} posts/reverse-chronological @var{posts} +Sort @var{posts}, a list of posts, in reverse chronological order. +@end deffn + +@deffn {Scheme Procedure} posts/group-by-tag @var{posts} +Create an association list of tags mapped to the posts in the list +@var{posts} that used them. +@end deffn + @node Readers @section Readers +@example +(use-modules (haunt reader)) +@end example + +The purpose of a reader is to translate the markup within a post file +into an SXML tree representing the HTML structure and associate some +metadata with it. + +@deffn {Scheme Procedure} make-reader @var{matcher} @var{proc} +Create a new reader. The reader is to be activated when +@var{matcher}, a procedure that accepts a file name as its only +argument, returns @code{#t}. When a post file matches, the procedure +@var{proc}, which also accepts a file name as its only argument, reads +the contents and returns a post object (@pxref{Posts}). +@end deffn + +@deffn {Scheme Procedure} reader? @var{object} +Return @code{#t} if @var{object} is a reader. +@end deffn + +@deffn {Scheme Procedure} reader-matcher @var{reader} +Return the match procedure for @var{reader}. +@end deffn + +@deffn {Scheme Procedure} reader-matcher @var{reader} +Return the read procedure for @var{reader}. +@end deffn + +@deffn {Scheme Procedure} reader-match? @var{reader} @var{file-name} +Return @code{#t} if @var{file-name} is a file supported by +@var{reader}. +@end deffn + +@deffn {Scheme Procedure} read-post @var{reader} @var{file-name} [@var{default-metadata}] +Read a post object from @var{file-name} using @var{reader}, merging +its metadata with @var{default-metadata}, or the empty list if not +specified. +@end deffn + +@deffn {Scheme Procedure} read-posts @var{directory} @var{keep?} @var{readers} [@var{default-metadata}] +Read all of the files in @var{directory} that match @var{keep?} as +post objects. The @var{readers} list must contain a matching reader +for every post. +@end deffn + +@deffn {Scheme Procedure} make-file-extension-matcher @var{ext} +Create a procedure that returns @code{#t} when a file name ends with +``.ext''. +@end deffn + +@defvr {Scheme Procedure} sxml-reader +A basic reader for posts written as Scheme code that evaluates to an +an association list. The special key @code{content} contains the post +body as an SXML tree. + +Example: + +@example +(use-modules (haunt utils)) + +`((title . "Hello, world!") + (date . ,(string->date* "2015-04-10 23:00")) + (tags "foo" "bar") + (summary . "Just a test") + (content + ((h2 "Hello!") + (p "This is Haunt. A static site generator for GNU Guile.")))) +@end example + +@end defvr + +@defvr {Scheme Procedure} html-reader +A basic reader for posts written in plain ol' HTML. Metadata is +encoded as the @code{key: value} pairs, one per line, at the beginning +of the file. A line with the @code{---} sentinel marks the end of the +metadata section and the rest of the file is encoded as HTML. + +Example: + +@example +title: A Foo Walks Into a Bar +date: 2015-04-11 20:00 +tags: bar +--- +<p> + This is an example using raw HTML, because Guile doesn't have a + Markdown parser. +</p> +@end example + +@end defvr + @node Pages @section Pages +@example +(use-modules (haunt page)) +@end example + +Page objects represent files that have yet to be written to disk. +Their contents may be any arbitrary object that their writer procedure +knows how to serialize. In practice, pages are almost always written +to disk as HTML or XML. + +@deffn {Scheme Procedure} make-page @var{file-name} @var{contents} @var{writer} +Create a new page object. The string @var{file-name} specifies where +the page should be written to in the file system. The procedure +@var{writer} is responsible for serializing @var{contents}. +@end deffn + +@deffn {Scheme Procedure} page? @var{object} +Return @code{#t} if @var{object} is a page object. +@end deffn + +@deffn {Scheme Procedure} page-file-name @var{page} +Return the file name string for @var{page}. +@end deffn + +@deffn {Scheme Procedure} page-contents @var{page} +Return the contents of @var{page}. +@end deffn + +@deffn {Scheme Procedure} page-writer @var{page} +Return the writer procedure @var{page}. +@end deffn + +@deffn {Scheme Procedure} write-page @var{page} @var{output-directory} +Write @var{page} to @var{output-directory}. +@end deffn + @node Assets @section Assets +@example +(use-modules (haunt asset)) +@end example + +Assets represent files on disk that should be copied verbatim to a +site's output directory. Common types of assets include CSS, +JavaScript, images, and fonts. + +@deffn {Scheme Procedure} make-asset @var{source} @var{target} +Create a new asset object. The @var{source} and @var{target} +arguments are file names that are relative to a site source and target +directory, respectively (@pxref{Sites}). +@end deffn + +@deffn {Scheme Procedure} asset? @var{object} +Return @code{#t} if @var{object} is an asset object. +@end deffn + +@deffn {Scheme Procedure} asset-source @var{asset} +Return the source file name for @var{asset}. +@end deffn + +@deffn {Scheme Procedure} asset-target @var{asset} +Return the target file name for @var{asset}. +@end deffn + +@deffn {Scheme Procedure} install-asset @var{asset} @var{prefix} +Install the source file of @var{asset} into the target directory +within @var{prefix}. +@end deffn + +@deffn {Scheme Procedure} directory-assets @var{directory} @var{keep?} @var{dest} +Create a list of asset objects to be stored within @var{dest} for all +files in @var{directory} that match @var{keep?}, recursively. +@end deffn + +@node Builders +@section Builders + +@menu +* Static Assets:: Images, CSS, JavaScript, etc. +* Blog:: Dear diary... +* Atom:: Atom feeds. +@end menu + +Builders are procedures that return one or more page objects +(@pxref{Pages}) when applied. A builder accepts two arguments: A site +(@pxref{Sites} and a list of posts (@pxref{Posts}). + +Haunt comes with a few convenient builders to help users who want to +create a simple blog with an Atom feed. + +@node Static Assets +@subsection Static Assets + +@example +(use-modules (haunt builder assets)) +@end example + +@deffn {Scheme Procedure} static-directory @var{directory} @ + [@var{dest} @var{directory}] + +Create a builder procedure that recursively copies all of the files in +@var{directory}, a file names relative to a site's source directory, +and copies them into @var{dest}, a prefix relative to a site's target +output directory. By default, @var{dest} is @var{directory}. +@end deffn + +@node Blog +@subsection Blog + +@example +(use-modules (haunt builder blog)) +@end example + +@deffn {Scheme Procedure} theme [#:name #:layout #:post-template #:collection-template] +Create a new theme named @var{name}. + +The procedure @var{layout} accepts three arguments: a site, a page +title string, and an SXML tree. Its purpose is to wrap the contents +of a post with the theme's header/footer and return the complete SXML +tree for a web page. + +The procedure @var{post-template} accepts a single argument: a post. +Its purpose is to return an SXML tree containing the contents of the +post, applying any desired post-processing operations. The values +returned from this procedure will be wrapped in the theme's layout. + +The procedure @var{collection-template} accepts four arguments: a +site, a title string, a list of posts, and a URL prefix string. Its +purpose is to return an SXML tree containing the body of the +collection page. The values returned from this procedure will be +wrapped in the theme's layout. +@end deffn + +@deffn {Scheme Procedure} theme? @var{object} +Return @code{#t} if @var{object} is a theme object. +@end deffn + +@deffn {Scheme Procedure} blog [#:theme #:prefix #:collections] +Create a builder procedure that transforms a list of posts into pages +decorated by @var{theme}, a theme object, whose URLs start with +@var{prefix}. + +Additionally, this builder creates pages that aggregate previews of +many posts corresponding to what is specified in the list +@var{collections}. Each collection is a three element list in the +form @code{(title file-name filter)}. + +@table @var + +@item title +The human readable name of the collection. + +@item file-name +The HTML file that will contain the rendered collection. + +@item filter +A procedure that accepts a list of posts as its only argument and +returns a new list of posts. The filter procedure is used to remove +and/or sort the posts into the desired form for the collection. For +example, a filter could sort posts in reverse chronological order or +select all posts that are written by a particular author. + +@end table + +By default, a single collection is created that lists posts in reverse +chronological order and writes to @file{index.html}. + +The default theme is intended only for testing purposes. + +@end deffn + +@node Atom +@subsection Atom + +@example +(use-modules (haunt builder atom)) +@end example + +@deffn {Scheme Procedure} atom-feed [#:file-name #:subtitle #:filter #:max-entries #:blog-prefix] +Return a builder procedure that renders a site's posts as an Atom +feed. All arguments are optional: + +@table @var + +@item file-name: +The page file name. The default is @file{feed.xml}. + +@item subtitle +The feed subtitle. The default is ``Recent Posts''. + +@item filter +The procedure called to manipulate the posts list before rendering. +The default is to keep all posts and sort them in reverse +chronological order. + +@item max-entries +The maximum number of posts to render in the feed. The default is 20. +@end table + +@end deffn + +@deffn {Scheme Procedure} atom-feeds-by-tag [#:prefix #:filter #:max-entries #:blog-prefix] +Return a builder procedure that renders an atom feed for every tag +used in a post. All arguments are optional: + +@table @var + +@item prefix +The directory in which to write the feeds. The default is +@file{feeds/tags}. + +@item filter +The procedure called to manipulate the posts list before rendering. +The default is to keep all posts and sort them in reverse +chronological order. + +@item max-entries +The maximum number of posts to render in each feed. The default is +20. + +@end table + +@end deffn + @node Contributing @chapter Contributing |