view release on metacpan or  search on metacpan

lib/App/FuguWeb/Site.pod  view on Meta::CPAN

root, and any directory that holds the project. They refuse the source
directory, and every directory of it. C<--out> reaches both commands,
and the C<out_dir> setting it overrides is checked in the description,
so the guard has to sit here as well.

A description that names neither directory takes the two defaults.

The source directory needs the rule because it reads like a built site:
a flat directory of files. The key directory is the worst case. Each
key file sits at its top level, where the clean takes a plain file, so
a clean of it would take the trust anchor of every release.

The output directory is the one exception below the source, and it
needs to be: the default output directory is F<web/build>, and it sits
inside the default source directory F<web>. The description names that
path, so a build owns it. Nothing else below the source is a build's.

The rule is deliberately not "inside the project". The tests and the CI
both build into a temporary directory outside it.

A C<..> in the target is resolved before the comparison.
C<File::Spec-E<gt>canonpath> leaves it alone by design, and a guard that
compared the uncollapsed form would let C<< <project>/.. >> through as a
directory it had never seen.

=head2 pod_date

The date that every POD page carries: the date of the last commit, and
today when git does not answer. git does not preserve file times, so a
build that read one would give different bytes on every checkout.

=head1 THE STAGING DIRECTORY

C<mandoc> decides between a local link and a link to the manual host by
looking for a file named C<%N.%S> in its working directory. Every mdoc
source is therefore copied into one directory under its
L<App::FuguWeb::Manual/staged_name>, and C<mandoc> runs there.

The directory lives inside the output directory, under F<.man>, and the
build removes it. Staging is a build detail: a published tree that
carried it would serve the mdoc sources beside the pages made from them.

=head1 THE KEY DIRECTORY

A description with a C<keys> block publishes the public keys of an
organization. The build copies each key file and the manifest pair as
they stand. It generates the C<KEYS> file, the human page, the Web Key
Directory tree and F<security.txt>. L<App::FuguWeb::Keys> holds the
wiring, and the Fugu modules hold every generic part.

The site build cannot sign, so the manifest pair is a source file. A
build that signed would prove that the builder holds the key, and
never that the release does.

A description with no C<keys> block writes no key directory, so every
site that predates it keeps its output.

=head1 ASSETS

An asset is any file directly in the source directory that the build
does not render: not a C<*.body.html> fragment, not Markdown, and not a
dot file. F<robots.txt> and F<CNAME> therefore need no entry in the
description, and a F<CLAUDE.md> beside them is not published.

Markdown in the source directory is either a page source, which a
C<page> block names and C<lowdown> renders, or notes for the
maintainers. Neither belongs in the output as it stands.

=head1 THE STYLESHEET

The base stylesheet ships with the tool, at F<share/fuguweb/style.css>,
and L<Fugu::File/share_path> finds it: in a checkout through this
module's location, and under the share tree of an installed App-FuguWeb
distribution. The C<stylesheet> setting overrides the search.

A stylesheet that is not found fails the build and names the path. A
site with no stylesheet must not look like a success.

=head1 SEE ALSO

L<App::FuguWeb>, L<App::FuguWeb::Config>, L<App::FuguWeb::Keys>, L<App::FuguWeb::Render>,
L<App::FuguWeb::Page>, L<App::FuguWeb::Index>, L<Fugu::File>

=head1 AUTHOR

Dick Olsson <hi@senzilla.io>