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_filesandedit_filescheck 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 isdata/site.yamlandtemplates/layout.html: if either is refused, nothing in that call is written. repeat: truemeans 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_publishis true when nothing is blocking.problemsare grouped by file. Blocking ones come first.seo_issuesare plain lines, never blocking. The rules are in the SEO reference.seohas 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.
Related pages
Something wrong on this page? Email support@siteship.ai. Checked on November 14, 2026.