diff options
| -rw-r--r-- | doc/haunt.texi | 114 |
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 |