Export World Anvil to Obsidian: Complete Migration Guide

World Anvil stores your worldbuilding in their database. That's convenient until you want to work offline, switch platforms, or just sleep better knowing your 400-article fantasy setting exists somewhere besides their servers. The export process exists, but it's not as simple as clicking "Download." You'll need an API key, a Gmail address, and some patience.

This guide covers the official World Anvil export, converting that export to Obsidian-compatible markdown files, and the limitations you should know about before you start.

What World Anvil Actually Exports

World Anvil's export feature gives you a ZIP archive containing your world's articles as JSON and basic HTML files. This includes all article states: drafts, private, and published content. Only the world owner can export, which protects collaborative worlds from unauthorized downloads.

The export contains your article content, metadata, and the relationships between articles. It does not include everything. Maps are notably absent from exports. World Meta (the high-level world description and settings) doesn't export either. Timelines export with limited formatting. If you've spent weeks perfecting your interactive maps or your world's meta presentation, those won't transfer.

Guild members (paid accounts) can export their entire world at once. Free accounts can only export articles individually, which becomes tedious fast if you've built anything substantial. The frequency of full exports also depends on your subscription tier: higher tiers allow daily exports, while lower tiers have longer cooldowns between exports.

Step 1: Export Your World from World Anvil

Start in your World Configuration page. Click the gear icon at the bottom of your world's dashboard, then look for "Open Tools & Advanced Actions" on the right side. Find the "EXPORT WORLD" option and select "Export this World."

World Anvil will ask for two things: your API key and a Gmail address. The API key authenticates your export request. Create one at worldanvil.com/api/auth/key if you don't already have one. The Gmail requirement exists because World Anvil sends your export as a Google Drive share rather than a direct download. This is frustrating if you don't use Gmail, but there's no workaround.

You can optionally specify a world name if you have multiple worlds and only want to export one. Leave it blank for a complete export of everything.

After you submit the export request, wait for the email confirmation. Large worlds take longer to compile. The email contains a link to download your ZIP archive. Save this file somewhere safe. This is your raw backup.

What's in the Export ZIP

Inside the ZIP you'll find folders organized by article type, each containing JSON files with your content and metadata. You'll also see basic HTML versions of your articles. The JSON contains everything: your article text, the BBCode formatting you've used, creation dates, privacy settings, and the internal IDs that World Anvil uses to link articles together.

You can read the HTML files directly in a browser if you just want to reference your content. But if you want to work with this content in another tool, you need to convert it.

Step 2: Convert to Obsidian with WorldAnvil-to-MD

The community-built WorldAnvil-to-MD tool converts your World Anvil export into markdown files that work with Obsidian. It's a Python script available on GitHub that processes your JSON files, extracts the content, converts BBCode to markdown where possible, downloads embedded images, and adds YAML frontmatter metadata to each file.

You'll need Python installed on your computer. If you don't have it, download it from python.org and install it. The script has no complex dependencies.

Setting Up the Tool

Download the WorldAnvil-to-MD repository from GitHub. Create a folder structure like this:

WorldAnvil-to-MD/
├── images/
├── World-Anvil-Export/
├── World-Anvil-Output/
└── WA-Parser.py

Unzip your World Anvil export into the World-Anvil-Export folder. Open the WA-Parser.py file and configure four variables:

source_directory points to your unzipped World Anvil export. Set this to 'World-Anvil-Export' if you followed the folder structure above.

destination_directory specifies where the converted markdown files will go. 'World-Anvil-Output' keeps things organized.

obsidian_resource_folder tells the script where images should be stored. Set this to 'images' and your images will end up in that folder, referenced correctly in your markdown files.

attempt_bbcode toggles BBCode-to-markdown conversion. Set it to True. The conversion isn't perfect (World Anvil's BBCode is extensive), but it handles common formatting like bold, italic, and links.

Running the Conversion

Open a terminal or command prompt, navigate to your WorldAnvil-to-MD folder, and run:

python WA-Parser.py

The script processes each article, prints progress to the console, and announces when it finishes. Check the output folder. You should see markdown files organized by article type, each with YAML frontmatter containing metadata like creation date, tags, and the original World Anvil article ID.

Importing into Obsidian

The safest approach: copy the contents of your output folder into a new Obsidian vault. Open Obsidian, create a new vault, and drag your converted files into it. This keeps your existing vaults untouched while you verify the conversion worked.

If you want to import directly into an existing vault, change the destination_directory to your vault's location and the obsidian_resource_folder to your vault's attachments folder. Back up your vault first. The script can overwrite files with matching names.

Once imported, your World Anvil articles become standard markdown files. Obsidian's linking features work with them. You can use the graph view to see how your articles connect. The YAML frontmatter makes them searchable and sortable.

What Doesn't Transfer (and Workarounds)

World Anvil's export has gaps. Knowing them in advance prevents nasty surprises.

Maps don't export. Your interactive maps with pins and overlays stay in World Anvil. If you've invested heavily in maps, screenshot them at high resolution before migrating. For the underlying geography, you'll need to recreate the interactive elements in Obsidian using plugins like Leaflet or simply embedding static images.

World Meta is missing. The introduction page, world settings, and high-level descriptions that appear on your world's landing page don't export. Copy this content manually from your World Anvil dashboard before you cancel any subscription.

BBCode conversion is imperfect. World Anvil uses extensive BBCode for advanced formatting: columns, containers, spoiler tags, accordion sections. The conversion tool handles basic formatting but struggles with complex layouts. You'll find some BBCode artifacts in your markdown files that need manual cleanup.

Internal links break. World Anvil links articles using internal IDs. The conversion tool creates markdown files with those IDs in the frontmatter, but it doesn't automatically rewrite [article:12345] references into Obsidian wiki-links. You'll need to manually update internal links or write a script to batch-convert them using the ID-to-filename mappings in your frontmatter.

Images require internet access during conversion. The WorldAnvil-to-MD tool downloads images from World Anvil's servers. If an image was deleted from World Anvil or their CDN is down, that image won't transfer. Run the conversion while you still have an active World Anvil account with access to your content.

Building a Backup Routine

Whether you're fully migrating or just want insurance, establish a regular export schedule. World Anvil's servers are reliable, but any cloud service can have outages, policy changes, or (in worst cases) shutdowns. Your worldbuilding represents hundreds of hours of creative work. Treat it like any valuable data.

Set a calendar reminder to export monthly. Store exports in multiple locations: your computer, an external drive, and a cloud backup service you control. Keep at least three versions so you can recover from corruption or accidental deletion.

If you're staying with World Anvil but want peace of mind, you don't need to convert to markdown every time. The raw ZIP export is a valid backup. You can always convert later if needed. What matters is having that ZIP file somewhere safe and current.

Why Obsidian Works for Worldbuilding

Obsidian stores everything as plain markdown files on your computer. No account required. No internet needed. No subscription fees. Your files are yours. You can open them in any text editor, sync them with any cloud service, and they'll remain readable decades from now.

The bi-directional linking works the same way World Anvil's article links do. Create a link with double brackets, and Obsidian connects the articles. The graph view shows your world's structure visually. Plugins extend functionality: add tables, Kanban boards, templates, and custom metadata.

The tradeoff is presentation. World Anvil excels at public-facing world pages with custom CSS, subscriber features, and beautiful displays. Obsidian is a personal knowledge base. If you want readers browsing your world online, World Anvil delivers that. If you want a private, fast, offline workspace for developing your world, Obsidian delivers that.

Many worldbuilders use both: Obsidian for drafting and development, World Anvil for publication and player access. The export/conversion workflow makes this viable, though it requires discipline to keep both systems synchronized.

Troubleshooting Common Problems

Export email never arrives. Check your spam folder. World Anvil sends from an automated address that filters sometimes catch. If you've waited more than an hour for a small world or a few hours for a large one, try the export again. Server load affects processing time.

Python script throws errors. Verify you're running Python 3. Some systems have both Python 2 and Python 3 installed; use python3 WA-Parser.py to be explicit. If the script can't find your export folder, double-check the path in your configuration variables. Use forward slashes or escaped backslashes in paths on Windows.

Converted files have weird characters. Encoding issues. Your World Anvil content likely contains special characters or non-English text that the conversion handles imperfectly. Most markdown editors handle UTF-8, but you may need to manually fix garbled characters in specific articles.

Images don't display in Obsidian. Check that your obsidian_resource_folder path matches Obsidian's actual attachments folder setting. Obsidian needs to know where to look for images. Open Obsidian's settings, go to Files & Links, and verify the attachment folder location.

After the Migration

Once your content lives in Obsidian, the real work begins. You now own your files completely. That means you're responsible for backups, organization, and maintenance that World Anvil handled automatically.

Spend time cleaning up the conversion artifacts. Fix broken links. Reorganize folders to match how you think about your world rather than World Anvil's category structure. Add tags and metadata that help you find content. Obsidian rewards this investment with speed and flexibility that browser-based tools can't match.

Your world didn't disappear when you exported it. It transformed. From a database on someone else's server into text files on your computer. Files you can edit, search, version-control, and keep forever. That's the point of the migration: ownership. Your world belongs to you.