# vanity --help

Usage: vanity <command> [flags]
 A static site generator CLI for Go vanity URLs.

Flags:
  -h, --help                 Show context-sensitive help.
      --log-level=STRING     Override log level (debug, info, warn, error) ($VANITY_LOG_LEVEL).
      --log-format=STRING    Override log format (text, json) ($VANITY_LOG_FORMAT).

Commands:
  init [flags]
    Generate a minimal .vanity.yml config file (use --verbose for full spec).

  generate [flags]
    Generate static HTML files from configuration.

  check [flags]
    Validate the .vanity.yml configuration.

  preview [flags]
    Generate in-memory and serve via local HTTP.

  serve [flags]
    Serve already-generated output directory.

  clean [flags]
    Remove the generated output directory.

  version [flags]
    Print version information.

Help:
  Run "vanity <command> --help" for more information on a command.

# .vanity.yml

# Your vanity URL domain (may include subdomains and url paths)
domain: example.com # REQUIRED
# Module definitions (at least one required)
modules:
  - name: my-module # REQUIRED: import path becomes {domain}/{module.name}
    repo: https://github.com/example/my-module # REQUIRED: full git repository URL

# .vanity.yml

# CLI behavior (overridable via --flags and VANITY_* env vars)
log:
  level: info # Options: debug | info | warn | error
  format: text # Options: text (human-friendly) | json (structured)
  color: true # Colorize text output (no effect on json)
# Output settings
output:
  dir: dist # Relative to .vanity.yml location
  clean: true # Remove output dir before generating
  index: true # Generate root index.html listing all modules
  not_found: true # Generate 404.html redirecting to index
  robots: true # Generate robots.txt (permissive, links to sitemap)
  sitemap: true # Generate sitemap.xml listing all module URLs
# Your vanity URL domain (may include subdomains and url paths)
domain: example.com # REQUIRED
# Default values applied to all modules (overridable per-module)
defaults:
  branch: main # Used in go-source meta tag URL templates (defaults to 'main')
  go_source: true # Include go-source meta tag for pkg.go.dev source links
  redirect_root: https://pkg.go.dev # Redirect = redirect_root/domain/name
# Module definitions (at least one required)
modules:
  - name: my-module # REQUIRED: import path becomes {domain}/{module.name}
    repo: https://github.com/example/my-module # REQUIRED: full git repository URL
    branch: main # Override defaults.branch for this module
    go_source: true # Override defaults.go_source for this module
    redirect: https://pkg.go.dev/example.com/my-module # Override browser redirect URL for this module
    local_path: ./my-module # Local checkout path (default: in-memory clone from repo remote if not specified)
    # Subpackage discovery settings (enabled by default in 'auto' mode - set subpackages:mode:off to disable)
    subpackages:
      mode: auto # Options: off | auto | explicit (defaults to 'auto')
      exclude: # Directories to skip in auto mode (defaults to [internal, testdata] in 'auto' mode)
        - internal
        - testdata
      paths: # Allow-list exact subpackage paths (explicit mode only)
        - sub/pkg
# Custom templates and static assets (all paths relative to .vanity.yml)
templates:
  index: templates/index.html # Custom body partial for the root index page
  module: templates/module.html # Custom body partial for module pages
  submodule: templates/submodule.html # Custom body partial for submodule pages (falls back to module)
  not_found: templates/404.html # Custom body partial for the 404 page
  partials: # Reusable template components (referenced via {{template "name" .}})
    - templates/header.html
    - templates/footer.html
  assets: # Static files/dirs copied verbatim into the output directory
    - css/
    - js/app.js

templates:
  assets:
    - css/          # css/style.css -> dist/css/style.css
    - js/app.js     # js/app.js -> dist/js/app.js