On this page
Migration is not done when wire build passes. Every migration leaves artifacts that Wire now detects and refuses. This checklist covers everything you need to clean up after migrating from WordPress, MkDocs, or any other platform.
Wire Detects Migration Artifacts
Wire refuses to build if it finds Python scripts at your site root. These are almost always leftover migration scripts:
BUILD REFUSED: Migration artifact at site root: convert_to_wire.py.
Delete migration scripts after migration is complete.
This gate exists because customers ran for weeks with migration junk in their repo, thinking everything was fine. Wire catches it now.
The Checklist
Delete Migration Scripts
Remove any .py files at your site root that were used during migration:
# Common migration leftovers
rm convert_to_wire.py
rm fix_internal_links.py
rm restructure_topics.py
rm extract_content.py
Wire allows setup.py and conftest.py -everything else at root level is flagged.
Remove Old Platform Configs
Delete configuration files from the previous platform:
# MkDocs
rm mkdocs.yml
# WordPress
rm wp-config.php
rm .htaccess # Wire generates its own
Your site is configured by wire.yml now. Old configs confuse new team members.
Update README
If your README still says "Built with MkDocs" or "WordPress site," update it:
# example.com
Built with [Wire](https://wire.wise-relations.com).
## Development
pip install wire
python -m wire.build
Clean Up SQL Dumps and Databases
WordPress migrations often leave large SQL dumps and SQLite databases at the repo root:
rm *.sql # MySQL dumps (can be hundreds of MB)
rm wordpress.db # SQLite extraction database
Keep .wire/gsc.db -that is your Google Search Console (GSC) data and Wire needs it.
Verify Redirects
Every old URL with search impressions needs a redirect or 410 entry in wire.yml:
python -m wire.chief data # Fetch latest GSC data
python -m wire.chief audit # Shows missing redirects
The audit will tell you exactly which URLs need attention. URLs with impressions but no page and no redirect are flagged.
Check Frontmatter
Wire rejects unknown frontmatter keys. If your migration carried over keys from the old platform, the build will refuse:
BUILD REFUSED: unknown frontmatter key(s): category, permalink.
Wire only supports: title, description, created, date, layout, ...
Remove or rename unsupported keys. Wire's supported keys are listed in the error message.
Backfill Created Dates
Migrations often set created: 2022-01-01 as a placeholder. Wire detects January 1st dates and refuses:
BUILD REFUSED: created date '2022-01-01' looks like a placeholder.
Run `python -m wire.migrate` to backfill from git history.
Fix it:
python -m wire.migrate --write
This reads git log to find the real first-commit date for each page.
Run a Full Build
After cleanup, run a full build and fix any remaining gates:
python -m wire.build
Wire will refuse if anything is still wrong. Every error message tells you exactly what to fix.
Common Mistakes
Leaving migration scripts "just in case." Delete them. They are in git history if you ever need them. Wire refuses to build with them present.
Keeping both wire.yml and mkdocs.yml. Wire reads wire.yml. mkdocs.yml does nothing but confuse people.
Placeholder dates. January 1st of any year is detected as a placeholder. Use wire.migrate to backfill real dates, or set them manually.
Unknown frontmatter keys. Wire is strict about what it accepts. If your old platform used category:, permalink:, or sidebar:, remove them. Wire uses tags:, URL-from-directory-structure, and short_title: instead.