FUGUWEB(1)

NAME
fuguweb - build a documentation website for a Perl project

SYNOPSIS
fuguweb [-hq] [- -project dir] command [argument ...]

DESCRIPTION
fuguweb builds one static website from the documentation that a Perl project already keeps: mdoc(7) manuals, POD sidecars, and Markdown. There is no templating language and no JavaScript. fuguweb runs mandoc(1), lowdown(1) and pod2man(1), and wraps each result in one shared chrome.

fuguweb operates on a project: a directory that has a .fuguwebrc file. The init command writes one. If you do not give - -project, fuguweb searches up from the current directory for a .fuguwebrc file. The directory that holds this file is the project root.

The build reads nothing from the network, writes nothing outside the output directory, and gives the same bytes for the same checkout.

The options are:

- -project dir
    Use dir as the project root, and do not search for it.

-q, - -quiet
    Do not show informational output.

-h, - -help
    Show the usage message.

These commands are available:

init [dir]
    Write a starter .fuguwebrc in dir (default: the current directory). The command refuses a directory that already has one.

build [- -out dir]
    Render the whole site. - -out overrides the out_dir setting, and a relative value is resolved against the project root, exactly as the setting is.

    The build also removes a page that the site no longer holds, so a manual that was renamed leaves nothing behind.

    The command checks the renderers first, and names the one that is missing. It then rejects a malformed manual source, because such a page must fail the build and not render badly.

clean [- -out dir]
    Remove the output directory.

    The command removes a built site and refuses anything else. A build writes one flat directory of files, so a target that holds a subdirectory, a symlink, or anything else that no build made is refused by name.

    Both build and clean also refuse the root of the filesystem, the home directory, the project root, and any directory that holds the project.

    With - -out the command needs no .fuguwebrc, because the target is named on the command line. clean is the command you reach for when the description is the thing that is broken.

check [- -out dir] [- -verbose]
    Check a built site: that every page and asset is there and is not empty, that every page has a title and the whole navigation, that every local link and every fragment resolves, that no reference is root-absolute or a ‘file:’ URL, that no local link reads as a URL scheme, that no manual cross-reference dangles, that every page is reachable from the front page, and that the output holds the site and nothing else.

    The command prints one line for each problem and exits 5. It says nothing and exits 0 when the site is good. - -verbose also notes every external link. The command never fetches one: the build and its checks touch no network.

FILES
.fuguwebrc
    The site description, at the project root.
share/fuguweb/style.css
    The base stylesheet, which ships with the tool. The stylesheet setting overrides the search for it.

EXIT STATUS
fuguweb exits with one of these values:

0   Success.
1   General error.
2   Invalid arguments.
3   Configuration error, or not in an fuguweb project.
4   A renderer failed.
5   The check found a problem.
6   A renderer is not installed.

EXAMPLES
Build the site and check it:

    $ fuguweb build --out web/build
    $ fuguweb check --out web/build

SEE ALSO
lowdown(1), mandoc(1), pod2man(1), mdoc(7)

The module documentation is in the .pod sidecars beside lib/App/FuguWeb/.

AUTHORS
Dick Olsson <hi@senzilla.io>