From bdf0ebe0e4e90b14812bccd5bf25d0aeac9ab7b2 Mon Sep 17 00:00:00 2001
From: David Thompson <dthompson2@worcester.edu>
Date: Wed, 27 Dec 2023 17:41:18 -0500
Subject: Add flat pages builder.

---
 doc/haunt.texi | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

(limited to 'doc')

diff --git a/doc/haunt.texi b/doc/haunt.texi
index 7857b38..50d1cf8 100644
--- a/doc/haunt.texi
+++ b/doc/haunt.texi
@@ -818,6 +818,7 @@ specification of Markdown, learn more about CommomMark
 
 @menu
 * Static Assets::              Images, CSS, JavaScript, etc.
+* Flat pages::                 Simple static pages.
 * Blog::                       Dear diary...
 * Atom::                       Atom feeds.
 * RSS::                        RSS feeds.
@@ -846,6 +847,64 @@ 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 Flat pages
+@subsection Flat pages
+
+@example
+(use-modules (haunt builder flat-pages))
+@end example
+
+Flat pages cover the simple case of converting a tree of files written
+in some markup language to full web pages.  Flat pages work great for
+the more informational parts of a website that don't require any fancy
+programming to generate, like an ``About me'' page.
+
+@deffn {Procedure} flat-pages directory [#:template] [#:prefix]
+
+Return a procedure that parses the files in @var{directory} and
+returns a list of HTML pages, one for each file.  The files are parsed
+using the readers configured for the current site.
+
+Each flat page starts with a metadata header.  Only a single piece of
+metadata is used, though: the title.
+
+Here's what a flat page written in Markdown might look like:
+
+@example
+title: About me
+---
+
+# About me
+
+Hello, I am Alice!  I'm a fictitious person made up for the purposes
+of demonstrating Haunt's flat page functionality.  I live here in this
+manual with my two cats: Bob and Carol.
+@end example
+
+The content of each flat page is inserted into a complete HTML
+document by the @var{template} procedure.  This procedure takes three
+arguments:
+
+@itemize
+@item the site object
+@item the page title string (from the metadata header)
+@item an SXML tree of the page body
+@end itemize
+
+@var{template} should return a single value: a new SXML tree
+representing a complete HTML page that presumably wraps the page body.
+
+Conveniently, the signature of @var{template} matches the blog theme
+layout procedure so that it can be reused for flat pages.  @xref{Blog}
+for more information.
+
+The structure of @var{directory} is preserved in the resulting pages
+and may be optionally nested within the directory @var{prefix}.  If no
+prefix is specified, the files are placed starting at the root of the
+site.
+
+@end deffn
+
 @node Blog
 @subsection Blog
 
-- 
cgit v1.2.3