Skip to main content

For your AI and the curious

Write-time checks

Every file is checked as it is written. What stops a write, what stops a publish, what is only advice, and the codes by topic.

On this page

Every file an AI writes to a SiteShip site is checked before it is saved. A file that would break the site is refused, with the problem, the file and the line. Everything else comes back as advice with the fix.

When a file is checked

  • On every write. write_files and edit_files check each file they touch: YAML and JSON, frontmatter, templates, forms and the stylesheet. A page is also rendered, so a Liquid error is caught at once.
  • On preview. The page is rendered and its links are checked.
  • On check. The whole site is checked without changing anything.
  • On publish. The whole draft is checked again. Blocking problems stop the publish.

Checks run on the draft. A refused file never reaches it.

Blocking and should-fix

Each diagnostic in a write's answer has a code, a message, the file and line, and a fix. It is one of two kinds:

Kind Meaning
blocking The file was refused, or the problem will stop a publish
should_fix Advice. The file was written. The fix names the SiteShip way, with the guide topic that explains it
{
  "written": ["pages/about.html"],
  "rejected": [
    { "path": "pages/contact.html", "error": "…", "problems": [
      { "blocking": true, "code": "author.form_file_input", "file": "pages/contact.html", "line": 14 }
    ] }
  ],
  "diagnostics": [
    { "should_fix": true, "code": "author.image_missing_alt", "file": "pages/about.html", "line": 31, "fix": "…" }
  ]
}

The example shows the shape, not every field.

  • Files stand alone. A refused file comes back in rejected, and the others in the same call are written. The exception is data/site.yaml and templates/layout.html: if either is refused, nothing in that call is written.
  • repeat: true means the same warning was left unfixed on the last write.
  • Information. A few codes only report what SiteShip understood, such as author.form_read. They need no fix.
  • Codes start author. when the person or AI writing the site can fix them.

Blocks publish, not the write

Three codes are blocking but never refuse a write, because a draft in progress may still hold them. They stop the publish instead:

Code Why it waits
author.placeholder_text Placeholder copy left in a page
author.generate_from_not_list A page-per-item template whose data list does not exist yet. The page may land before its data
author.broken_reference A slug that points at no item in the list it names. The reference may land before the item

Two more problems are advice on a write and blocking at publish: an image that does not exist (author.image_missing), and a link to a page that does not exist, when it sits in a template or data file (author.dead_internal_link). A site with no home page can't be published (author.no_homepage).

Refused files

These refuse the file. Fix it and send only that file again.

What was written Code
Frontmatter that is not valid YAML author.frontmatter_yaml_invalid
A data file that does not parse author.data_file_invalid
A data/site.yaml that does not parse, or has a field of the wrong kind author.site_yaml_invalid, author.site_config_invalid
A Liquid error when the page renders author.template_render_error
A stray, mismatched or unclosed tag author.html_unexpected_closing_tag, author.html_mismatched_closing_tag, author.html_unclosed_tag
A page with its own <html>, <head> or <body> author.page_has_document_shell
A layout or partial that does not exist author.layout_missing, author.component_missing, author.item_template_missing
@import, or markup, in theme.css author.theme_css_import, author.theme_css_markup
Bootstrap or another CSS framework author.css_framework
Alpine.js attributes, or Bootstrap's data-toggle author.alpine_unsupported, author.bootstrap_toggle
A data-open or data-tab that points at nothing author.behaviour_target_missing
access: or members_only: in frontmatter author.membership_unsupported
A [param] page with no list to read author.dynamic_route_missing_generate
Redirects that loop author.redirect_loop
A form problem The author.form_* codes in the Forms reference

A path outside the site's source folders is refused too. The writable paths are listed under write_files in The connector tools.

The check report

check takes a site and returns one report:

{
  "pages_checked": 43,
  "ready_to_publish": true,
  "blocking": 0,
  "warnings": 2,
  "by_code": { "author.image_missing_alt": 2 },
  "problems": { "pages/about.html": [ { "should_fix": true, "code": "author.image_missing_alt", "lines": [31, 58] } ] },
  "seo_issues": ["/about: description is only 38 characters; aim for 120-160"],
  "seo": [ { "path": "/about", "links_in": 3 } ]
}
  • ready_to_publish is true when nothing is blocking.
  • problems are grouped by file. Blocking ones come first.
  • seo_issues are plain lines, never blocking. The rules are in the SEO reference.
  • seo has a row for each page: title, description, h1, share image, words, images and links in.

The same checks run inside publish, so a draft that passes check and has not changed since is not stopped by a problem there.

Code list by topic

Every code below is advice unless the tables above say it blocks.

Pages and frontmatter

Code Meaning
author.frontmatter_typo An unknown key close to a known field
author.frontmatter_schema_invalid A known field with the wrong kind of value
author.page_title_missing A page with no title
author.multiple_h1 More than one <h1> on a page
author.unknown_variable A variable that does not exist, which would print nothing
author.unknown_filter A Liquid filter that does not exist
author.script_in_markdown Behaviour code in a Markdown page
author.reserved_path A page at an address SiteShip keeps for itself. For most such addresses it blocks publish

Layouts and partials

Code Meaning
author.layout_missing_content_slot A layout with no {{ content }}
author.engine_head_tag A layout or head.html writes a tag SiteShip writes itself. The copy is dropped
author.head_tags_outside_head The same, in a page
author.shell_duplicated_in_page The header or footer copied into a page
author.template_cascade_mismatch A template in the wrong folder for the pages it is meant for
author.unused_component Information: a partial nothing renders

The SiteShip way

Code Meaning
author.hardcoded_site_fact A phone number or email typed into a page, not printed from data/site.yaml
author.menu_hardcoded The menu typed into the header, not looped from site.menu
author.list_in_html The same block of markup repeated, where a data list and a loop belong
author.hand_written_schema Hand-written business schema
author.engine_feature_reimplemented A hand-built copy of something built in: analytics, the cookie banner or a form backend
author.liquid_in_json Liquid inside JSON-LD without the json filter

Styling

Code Meaning
author.style_block, author.inline_style A <style> block, or heavy style="" attributes
author.external_stylesheet An outside stylesheet that is not a font
author.theme_component_class @apply or a component class in theme.css
author.theme_css_compile The stylesheet does not compile. Blocking when theme.css itself was written
author.class_no_css A colour or font class whose token does not exist, so it does nothing
author.palette_drift Information: many raw colours where theme tokens belong

Scripts and behaviours

Code Meaning
author.inline_event_handler An onclick= or similar attribute
author.inline_script_large A long inline script that belongs in assets/js/
author.document_write document.write in a script
author.cdn_unpinned A library loaded from a CDN with no pinned version
author.tracker_without_consent A tracking pixel on a site with no cookie banner

Links and images

Code Meaning
author.dead_internal_link A link to a page that does not exist
author.link_relative, author.image_relative A relative address. Start it with /
author.image_missing An image file that does not exist
author.image_missing_alt An image with no alt text
author.image_localhost An image address on a local machine

Links to other websites are not checked.

Data and generated pages

Code Meaning
author.hand_typed_count A count typed into a data item that disagrees with the list it counts
author.generate_no_pages, author.generate_items_skipped A list that makes no pages, or items missing the field the address needs
author.dynamic_route_param_missing, author.dynamic_route_param_unused A page-per-item path and its mapping disagree
author.slug_not_url_safe A slug that is not safe in an address
author.global_collection_unknown globalCollections names a folder that is not a collection

Business details and search

Code Meaning
author.hours_unreadable hours can't be turned into opening hours, so the schema gets none
author.site_type_invalid Blocking: type in data/site.yaml is not one of SiteShip's site types
author.search_fields_ignored Information: search.fields on a page that is not generated from data, where it does nothing
author.search_index_full Information: the site has more page text than site search keeps. Later pages are found by title, description and keywords only
author.canonical_url_invalid, author.og_url_invalid, author.og_image_url_invalid, author.twitter_image_url_invalid, author.favicon_url_invalid, author.script_url_invalid An address for a head tag or a scripts: entry that SiteShip can't use

For why SiteShip checks at write time, see "We measure it" on The engine.

Something wrong on this page? Email support@siteship.ai. Checked on November 14, 2026.

Built in a chat

Home page of Low Tide Coffee, a coffee shop website built with SiteShip

Coffee shop

Low Tide Coffee

The prompt that built it

Build a website for Low Tide Coffee, a small coffee shop and roastery at 14 Harbor Street, Beaufort, SC. We roast our own beans in the back room. Open every day 7am to 3pm. Phone (843) 555-0114. A menu with prices (drip, cortado, cold brew, oat-milk latte, biscuits and pastries). Two house blends sold in the shop: Marsh Blend and Dock Street Dark. Catering for offices and events, with an enquiry form (name, email, date, number of people, message). Pages: Home, Menu, Our beans, Catering. Look: warm and moody. Dark roasted brown and cream with a burnt-orange accent, an elegant serif for headlines with a clean sans for text, a photo of coffee being poured in the hero, and a menu laid out like a printed cafe menu.

Swap in your own business details. Your AI will ask five quick questions if anything is missing.

Add SiteShip to your AI

SiteShip is a connector you add once. You'll create your free account when you connect. No card needed.

https://app.siteship.ai/mcp
ChatGPT
  1. Open ChatGPT on the web and go to Settings, then Apps and connectors.
  2. Choose Add custom connector (you may need to switch on Developer mode under Advanced).
  3. Name it SiteShip, paste the address above and choose OAuth.
  4. Sign in to SiteShip when asked, then start a new chat and say: Get started with SiteShip.

Custom connectors need a paid ChatGPT plan.

Claude
Add to Claude

This opens Claude with SiteShip filled in. Click Add, sign in to SiteShip, then say: Get started with SiteShip.

Or add it by hand

  1. Open Claude and go to Customize, then Connectors.
  2. Click Add, then Add custom connector.
  3. Name it SiteShip and paste the address above.
  4. Sign in to SiteShip when asked, then start a new chat and say: Get started with SiteShip.
Grok

Go to grok.com/connectors, choose New Connector, then Custom, and paste the address above.

Gemini

In the Gemini web app, open Apps/Connectors settings, add a custom connector and paste the address above. (US accounts only for now.)

Other AI apps and coding tools
  1. Open your AI app's settings and look for Connectors, Apps, Integrations or MCP servers.
  2. Add a custom (remote) connector and paste the address above.
  3. Sign in to SiteShip when asked, then start a new chat and say: Get started with SiteShip.

Works with any app that accepts a remote MCP server, including coding tools such as Claude Code, Cursor, VS Code and Codex.

Coding tools

Claude Code

claude mcp add --transport http siteship https://app.siteship.ai/mcp

Codex

codex mcp add siteship --url https://app.siteship.ai/mcp

Then say: Get started with SiteShip.