summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2023-12-27 17:41:18 -0500
committerDavid Thompson <dthompson2@worcester.edu>2023-12-28 09:27:28 -0500
commitbdf0ebe0e4e90b14812bccd5bf25d0aeac9ab7b2 (patch)
tree3efb892173ecc626da791b0aa1c6ba727edfe674 /doc
parente94110b8b12645aa22469a73951905b6e55d3120 (diff)
Add flat pages builder.
Diffstat (limited to 'doc')
-rw-r--r--doc/haunt.texi59
1 files changed, 59 insertions, 0 deletions
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