On this page
Christopher Helm Creator of Wire

Wire is binary. Your build either passes or it refuses with a clear error message. There are no warnings you can ignore, no flags to skip checks, no --force to push through. If Wire refuses, you fix the issue. This page lists every gate.

Why Binary

Two customers migrated to Wire and worked for two weeks with builds that passed. Their sites had auto-translated garbage, broken nav labels, placeholder dates, and leftover migration scripts. Wire said nothing. They called the CEO.

That does not happen anymore. Wire now checks 13 structural and content gates before building. Every gate crashes with an error that tells you exactly what is wrong and how to fix it.

Structure Gates

Missing Nav Config

Trigger: No nav: key in wire.yml.

wire.yml missing required field(s): nav.
Nav is a strategic decision - Wire does not guess your site structure.
Define nav: in wire.yml.

Fix: Add an explicit nav: section to wire.yml. List every page and section. Wire does not auto-discover navigation - your site structure is a deliberate decision, not something to guess at.

Language Asymmetry

Trigger: A configured language has less than 20% of the default language's page count.

BUILD REFUSED: Language 'en' has 9 pages (1% of 'de' with 667).
This looks like a ghost-town translation.
Remove 'en' from languages config or add content.

Fix: Either add real content to the small language or remove it from wire.yml. Auto-translated pages with no human review should not be a separate language -they dilute your site.

Orphan Language Directory

Trigger: Your docs/ contains directories that look like language codes (de, en, fr) but languages: is not configured in wire.yml.

Fix: Either configure languages: in wire.yml or rename the directories to not match ISO 639-1 codes.

Migration Artifacts

Trigger: Python scripts (.py files) at your site root.

BUILD REFUSED: Migration artifact at site root: convert_to_wire.py.
Delete migration scripts after migration is complete.

Fix: Delete the scripts. They are in git history if you need them. See Post-Migration Cleanup.

Redirect in Frontmatter

Trigger: A page has redirect: in its YAML frontmatter.

BUILD REFUSED: 'redirect:' in frontmatter is not supported.
Add redirect to wire.yml instead:
redirects:
  /old/path/: /new/path/

Fix: Wire handles redirects in wire.yml and .wire/redirects.yml, not in frontmatter. Move the redirect there.

Unknown Frontmatter Keys

Trigger: A page has a frontmatter key that Wire does not recognize.

BUILD REFUSED: unknown frontmatter key(s): category, permalink.
Wire only supports: title, description, created, ...

Fix: Remove or rename the key. The error message lists every supported key. Common migrations from WordPress or MkDocs carry over unsupported keys.

Empty Topic Directory

Trigger: A topic directory has an index page but no content pages.

Fix: Add content pages to the topic or remove the empty directory. A topic with only an index creates a broken nav section with nothing to navigate to.

Missing CTA

Trigger: A site with topics does not configure header.cta in wire.yml.

Fix: Add a CTA to your header config, or set header.cta: false to explicitly disable it.

Missing Offerings

Trigger: A site with topics does not configure header.offerings in wire.yml.

Fix: Add header.offerings: topicname (resolves from a topic) or header.offerings: false to explicitly disable it.

Missing Logo or Favicon

Trigger: logo or favicon is not set in wire.yml.

Fix: Add logo: assets/logo.svg (path to your logo file) or logo: false for text-only. Same for favicon.

Missing Sidebar CTA

Trigger: extra.wire.sidebar_cta is not configured in wire.yml.

Fix: Article pages need a sidebar CTA card. Add title, link, and link_text under extra.wire.sidebar_cta.

Missing Labels

Trigger: extra.wire.labels is not configured in wire.yml.

Fix: Add on_this_page, related_articles, and read_more under extra.wire.labels. Sites with discovery steps also need discovery_start and discovery_read.

Content Gates

Short Title Trailing Fragment

Trigger: A short_title ends with a preposition (für, and, with, in, ...) or punctuation (-, :).

BUILD REFUSED: short_title 'KI Anwendungen für' ends with
trailing preposition 'für' -incomplete label

Fix: Complete the label or rephrase it. Nav labels must be self-contained -a trailing preposition means the title was truncated.

Numbered Slug

Trigger: A page slug starts with a number prefix like 2-adding-chatbot/ or 7-advanced/.

BUILD REFUSED: slug '2-adding-chatbot' starts with a number.
Use descriptive slugs instead of numbered directories.

Fix: Rename the directory to a descriptive slug. Date-based slugs (like 2026-03-14-news-title/) are allowed -only short numeric prefixes (1-2 digits) are flagged.

Numbered Heading Prefix

Trigger: The majority of H2/H3 headings on a page start with numbered patterns like ## 1. Introduction, ## 2. Methods, ## 3. Results. A single numbered heading among normal ones is fine -this only fires when the whole document is mechanically numbered.

This is a lint rule (RULE-67). It blocks the build like all lint rules.

Fix: Use descriptive headings without manual numbering. The document structure provides the hierarchy.

Placeholder Date

Trigger: A created date falls on January 1st of any year.

BUILD REFUSED: created date '2022-01-01' looks like a placeholder.
Run `python -m wire.migrate` to backfill from git history.

Fix: Run python -m wire.migrate --write to set real dates from git history, or set the date manually.

Duplicate Titles Across Languages

Trigger: The same page title appears in two different language versions of the site.

This is currently a warning, not a build refusal. It flags likely untranslated content.

Fix: Translate the title or differentiate it for the target language.

There Is No Escape Hatch

Wire has no --skip-gates, no --force, no --no-validate. If a gate fires, you fix the issue. The gates exist because real customers hit real problems that Wire should have caught.

If you believe a gate is wrong for your use case, open an issue. Do not work around it.