summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorFilip Lajszczak <filip@lajszczak.dev>2023-11-12 14:44:53 +0000
committerDavid Thompson <dthompson2@worcester.edu>2023-11-12 12:40:58 -0500
commit749cdfad1da20c7dd63ec04bf43f83ec708b2b30 (patch)
tree9f0a6bfe2491980a9ddb97aafdd5f3027efeec50 /doc
parent2a9d4173744d87eb18068d159a1e0cde56c7de77 (diff)
doc: Document publishers.
Diffstat (limited to 'doc')
-rw-r--r--doc/haunt.texi114
1 files changed, 113 insertions, 1 deletions
diff --git a/doc/haunt.texi b/doc/haunt.texi
index 3deba4c..68229fc 100644
--- a/doc/haunt.texi
+++ b/doc/haunt.texi
@@ -156,6 +156,14 @@ later (for Skribe support)
@item
@url{https://github.com/OrangeShark/guile-commonmark, guile-commonmark}
version 0.1 or later (for CommonMark support)
+@item
+@url{https://rsync.samba.org/, rsync}
+version 0.2 or later (for rsync publishing)
+@item
+@url{https://sr.ht/~emersion/hut/, hut}
+version 0.2 or later (for Sourcehut publishing)
+@item
+@url{https://www.gnu.org/software/tar/, Tar} (for Sourcehut publishing)
@end itemize
@node Building
@@ -291,6 +299,7 @@ programming interfaces.
@menu
* Invoking haunt build:: Build the website.
* Invoking haunt serve:: Serve the website over HTTP.
+* Invoking haunt publish:: Publish the website.
@end menu
The Haunt command-line interface is composed of many subcommands. The
@@ -366,6 +375,32 @@ Automatically rebuild the site when source files change.
@end table
+@node Invoking haunt publish
+@section Invoking @command{haunt publish}
+
+The @command{haunt publish} command deploys the site to a remote
+location. The site must have already been built via @command{haunt
+build} before running @command{haunt publish}.
+
+Usage:
+
+@example
+haunt publish
+@end example
+
+By default, Haunt uses the publisher named @code{production} defined
+for the current site. However, Haunt supports multiple publishers.
+Consider the use case where an author wants to publish to a staging
+environment to confirm that everything looks good on a real web server
+before publishing to production. To use a non-production publisher,
+simply say so at the command line:
+
+@example
+haunt publish staging
+@end example
+
+For details on how to configure publishers, @pxref{Publishers}.
+
@node Programming Interface
@chapter Programming Interface
@@ -376,6 +411,7 @@ Automatically rebuild the site when source files change.
* Pages:: HTML/XML pages.
* Assets:: Images, stylesheets, etc.
* Builders:: Web page builders.
+* Publishers:: How to publish your site.
@end menu
Haunt is a fully-programmable system composed of several Guile Scheme
@@ -398,7 +434,7 @@ output files are written to, etc.
[#:file-filter @code{default-file-filter}] @
[#:build-directory "site"] [#:default-metadata '()] @
[#:make-slug @code{post-slug}] [#:readers '()] @
- [#:builders '()]
+ [#:builders '()] [#:publishers '()]
Create a new site object. All arguments are optional:
@table @var
@@ -430,6 +466,9 @@ A list of reader objects for processing posts.
@item builders
A list of procedures for building pages from posts.
+@item publishers
+A list of publisher objects for upload site contents to a remote location
+
@end table
@end deffn
@@ -470,6 +509,11 @@ Return the list of reader procedures for @var{site}.
Return the list of builder procedures for @var{site}.
@end deffn
+@deffn {Scheme Procedure} site-publishers @var{site}
+Return the list of publisher objects for upload @var{site} contents to a
+remote location.
+@end deffn
+
@node Posts
@section Posts
@@ -981,6 +1025,74 @@ The maximum number of posts to render in each feed. The default is
@end deffn
+@node Publishers
+@section Publishers
+
+@example
+(use-modules (haunt publisher))
+@end example
+
+The purpose of a publisher is to deploy a built site. Haunt comes
+with some built-in publishers, but custom publishers can be created
+with the following interface.
+
+@deffn {Scheme Procedure} make-publisher @var{name} @var{proc}
+Create a new publisher.
+@end deffn
+
+@deffn {Scheme Procedure} publisher? @var{object}
+Return @code{#t} if @var{object} is a publisher.
+@end deffn
+
+@deffn {Scheme Procedure} publisher-name @var{publisher}
+Return the publisher name.
+@end deffn
+
+@deffn {Scheme Procedure} publisher-proc @var{reader}
+Return the publisher procedure for @var{publisher}.
+@end deffn
+
+@deffn {Scheme Procedure} publish @var{publisher} @var{site}
+Publish @var{site} with @var{publisher}.
+@end deffn
+
+@deffn {Scheme Procedure} run-command @var{program} @var{args}
+Run command @var{program} with @var{args} arguments.
+@end deffn
+
+Haunt comes with the following built-in publishers:
+
+@node Rsync
+@subsection Rsync
+
+@example
+(use-modules (haunt publisher rsync))
+@end example
+
+@deffn {Scheme Procedure} rsync-publisher [#:name 'production] [#:destination] @@
+ [#:user] [#:host] [#:name] [#:rsync] @@
+ [#:flags '("--compress" "--delete" "--progress" "--recursive" "--verbose")]
+
+Return a new publisher named @var{name} that publishes a site to
+@var{destination}, either locally or to a remote host if @var{host}
+and/or @var{user} arguments are specified. Passing @var{rsync}
+overrides the @command{rsync} executable used. Passing @var{flags}
+overrides the set of command line flags used.
+@end deffn
+
+@node Sourcehut
+@subsection Sourcehut
+@example
+(use-modules (haunt publisher sourcehut))
+@end example
+
+@deffn {Scheme Procedure} sourcehut-publisher [#:name 'production] [#:hut] [#:tar]
+Return a new publisher named @var{name} that publishes a site to
+Sourcehut pages using the site's configured domain. Passing @var{hut}
+and/or @var{tar} overrides the default @command{hut} and @command{tar}
+executables used.
+@end deffn
+
@node Contributing
@chapter Contributing