.zine.ziggy-schema

$ = Config

/// This is the schema of a Zine website config file, usually named 'zine.ziggy'.
struct Config {
    /// A semver string representing the version of Zine that your website
    /// requires. Used by GitHub / Forgejo actions to select automatically
    /// the right version of Zine to fetch, see the 'Deploying' section of
    /// https://zine-ssg.io/docs/.
    zine_version: bytes,
    /// Should external links generated by SuperMD automatically add
    /// `target="_blank"`? Defaults to `false`.
    ///
    /// Note: you can override this setting on each link by using explicit
    /// syntax (e.g. `[my link]($link.url(https://example.com).new(true))`)
    auto_target_blank: ?bool,
    /// Your website definition
    site: Site,
    /// User-defined properties that you can reference from SuperHTML via
    /// '$site.custom'.
    custom: {:}any,
}

union Site {
    simple: Simple,
    multilingual: Multilingual,

    struct Simple {
        title: bytes,
        /// URL where the website will be hosted.
        /// It must not contain a subpath, see `url_path_prefix`.
        host_url: bytes,
        /// Set this value if your website is hosted under a subpath of `host_url`.
        ///
        /// `host_url` and `url_prefix_path` are split to allow the development
        /// server to generate correct relative paths when serving the website
        /// locally.
        url_path_prefix: ?bytes,

        /// Directory containing your SuperHTML layouts.
        layouts_dir_path: bytes,
        /// Directory containing your SuperMD content.
        content_dir_path: bytes,
        /// Directory containing your site-wide assets.
        assets_dir_path: bytes,

        /// Subpaths in `assets_dir_path` that will be installed unconditionally.
        /// All other assets will be installed only if referenced by a content file
        /// or a layout by calling `$site.asset('foo').link()`.
        ///
        /// Examples of incorrect usage of this field:
        /// - site-wide CSS files (should be `link`ed by templates)
        /// - RSS feeds (should be generated by defining `alternative` pages)
        ///
        /// Examples of correct usage of this field:
        /// - `favicon.ico` and other similar assets auto-discovered by browsers
        /// - Font files only referenced inside of CSS files.
        static_assets: []bytes,
        /// When enabled, Zine will automatically add 'width' and 'height'
        /// attributes to <img> elements for local assets.
        /// Be aware that setting 'width' and 'heigth' of an image will in some
        /// circumstances cause browsers to distort images.
        ///
        /// This problem can be solved by adding the following CSS code to your
        /// site:
        ///
        ///    img { height: auto; }
        ///
        image_size_attributes: ?bool,
    }

    struct Multilingual {
        /// URL where the website will be hosted.
        /// It must not contain a subpath, see `Locale.output_prefix_override`.
        host_url: bytes,
        /// Directory that contains mappings from placeholders to translations,
        /// expressed as Ziggy files.
        ///
        /// Each Ziggy file must be named after the locale it's meant to offer
        /// translations for.
        i18n_dir_path: bytes,
        /// Directory containing your SuperHTML layouts.
        layouts_dir_path: bytes,
        /// Directory containing your site-wide assets.
        assets_dir_path: bytes,
        /// Location where site- and build- assets will be installed. By default
        /// assets will be installed directly in the output location.
        ///
        /// In mulitilingual websites Zine will create a single copy of
        /// site assets which will then be installed at this location. It
        /// will be your duty to then copy this directory elsewhere if
        /// needed in your deployment setup (e.g. when deploying different
        /// localized variants to different hosts).
        ///
        /// NOTE: *page* assets will still be installed next to their
        /// relative page.
        assets_prefix_path: ?bytes,
        /// Subpaths in `assets_dir_path` that will be installed unconditionally.
        /// All other assets will be installed only if referenced by a content file
        /// or a layout by using `$site.asset('foo').link()`.
        ///
        /// Examples of incorrect usage of this field:
        /// - site-wide CSS files (should be `link`ed by templates)
        /// - RSS feeds (should be generated by defining `alternative` pages)
        ///
        /// Examples of correct usage of this field:
        /// - `favicon.ico` and other similar assets auto-discovered by browsers
        /// - Font files only referenced inside of CSS files.
        static_assets: []bytes,
        /// A list of locales of this website.
        ///
        /// For each entry the following values must be unique:
        ///   - `code`
        ///   - `output_prefix_override` (if not null) + `host_url_override`
        locales: []Locale,
        /// When enabled, Zine will automatically add 'width' and 'height'
        /// attributes to <img> elements for local assets.
        /// Be aware that setting 'width' and 'heigth' of an image will in some
        /// circumstances cause browsers to distort images.
        ///
        /// This problem can be solved by adding the following CSS code to your
        /// site:
        ///
        ///    img { height: auto; }
        ///
        image_size_attributes: ?bool,

        struct Locale {
            /// A language-NATION code, e.g. 'en-US', used to identify each
            /// individual localized variant of the website.
            ///
            /// Must be unique.
            code: bytes,
            /// A name that identifies this locale, e.g. 'English'
            name: bytes,
            /// Content dir for this locale,
            content_dir_path: bytes,
            /// Site title for this locale.
            site_title: bytes,
            /// Set to a non-null value when deploying this locale from a dedicated
            /// host (e.g. 'https://us.site.com', 'http://de.site.com').
            ///
            /// It must not contain a path other than '/'.
            host_url_override: ?bytes,
            /// |  output_ |     host_     |     resulting    |    resulting    |
            /// |  prefix_ |      url_     |        url       |      path       |
            /// | override |   override    |      prefix      |     prefix      |
            /// | -------- | ------------- | ---------------- | --------------- |
            /// |   null   |      null     | site.com/en-US/  | zig-out/en-US/  |
            /// |   null   | "us.site.com" | us.site.com/     | zig-out/en-US/  |
            /// |   "foo"  |      null     | site.com/foo/    | zig-out/foo/    |
            /// |   "foo"  | "us.site.com" | us.site.com/foo/ | zig-out/foo/    |
            /// |    ""    |      null     | site.com/        | zig-out/        |
            ///
            /// The last case is how you create a default locale.
            output_prefix_override: ?bytes,
        }
    }
}