SOFFIO(1)                     System Reference                     SOFFIO(1)

NAME
    soffio - A minimalist, strict static site generator

DESCRIPTION
    Soffio takes text in and outputs HTML. It reads .soffio files,
    validates the integrity of the entire corpus (internal links,
    footnotes, and assets), and writes a static site preserving the
    input directory structure.

    It has zero external dependencies. It does not guess. If a link
    is broken, the build fails.

FEATURES
    Strict Validation: Fails on broken links, missing notes, or assets.
    Privacy Guards: Public documents cannot link to private ones.
    UNIX Pathing: Standard POSIX rules for relative cross-folder links.
    Dual Mode: Directory generator or stdin/stdout UNIX filter.
    Web Standards & Syndication: Generates RSS feeds, XML sitemaps,
    robots.txt, web app manifests (manifest.json), and 404 error pages.
    Agnostic Templates: Sort and format data entirely at the presentation layer.

BUILD
    Requires Go 1.26 or higher.

    make         build soffio and preview binaries
    make clean   remove binaries and generated output

USAGE
    Generator mode:
        soffio [flags] <src_dir>

    Pipe mode:
        soffio < input.soffio > output.html

    Preview server:
        preview [flags] [dir]

    Run 'soffio -help' or 'preview -help' for flag details.

MARKUP SYNTAX
    A document requires a frontmatter, a blank line, and the body.
    Frontmatter keys include 'id', 'title', 'layout', 'visibility',
    and 'notes_title'.

    == id | Title                     Section header
    *text*                            Bold
    _text_                            Italic
    (Label -> target)                 Hyperlink
    :: img: /static/path | caption    Image block
    - text                            List item
    :: note: id | text                Footnote definition
    (*note-id)                        Footnote reference

TEMPLATES
    Soffio exposes the document tree to standard Go HTML templates.
    Presentation logic is handled entirely by the theme. Use the built-in
    sortBy function to order a document's children by any frontmatter key:

        {{ range sortBy .Children "event_date" }}
          <a href="{{ $.BaseURL }}/{{ .ID }}.html">{{ .Title }}</a>
        {{ end }}

ROUTING & LINKS
    The filesystem scopes the output directory. <input>/it/about.soffio
    with 'id: my-id' becomes <output>/it/my-id.html.

    Links use (Label -> target).
    Targets without a leading slash are resolved relative to the
    current document's directory (zero-config i18n).
    Targets with a leading slash are resolved from the site root.
    A target may include a #section suffix to point at a specific
    heading id within a document (e.g. document-id#section-id).
    Omitting the path before # targets a heading in the current document.

ASSETS
    Static assets are kept in the 'static' directory (or via -s).
    During build, they are mirrored to the output folder.
    Asset paths in documents must be explicitly prefixed from the site root
    (e.g. :: img: /static/img/file.jpg | caption).

AUTHOR
    Written and designed by Jacopo Costantini.

COPYRIGHT AND LICENSE
    Copyright (C) 2026 Jacopo Costantini.

    Soffio is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published
    by the Free Software Foundation, either version 3 of the License,
    or (at your option) any later version.

    See the LICENSE file in the source distribution for full details.