Turn a public WordPress site into an Astro 5 project with one command: posts and pages as Markdown, your images, and every post at the URL it has today.
npx wordpress-to-astro https://your-site.comNo plugin to install, no login, no database export. It reads the same public REST API any visitor can, and writes a plain Astro project you can run, edit and host anywhere.
$ npx wordpress-to-astro https://wptavern.com --max-posts 20
Reading https://wptavern.com ...
Converted WP Tavern (https://wptavern.com)
20 posts, 14 pages, 6 categories, 16 tags
21 images downloaded
34 URLs kept as they are
Notes:
- Your site has 6637 posts and 14 pages; this conversion includes the newest 20 posts and 14 pages. Raise the post limit (up to 100000) or add the rest by hand.
- 5 blocks did not convert cleanly to Markdown (tables, embeds, galleries, page-builder layouts) and were kept as HTML inside the Markdown files, so nothing is lost. They may look plainer without your theme's styles.
- 3 items contain a form that posted back to WordPress. The form is still in the page but will not submit; point it at a form service.
Wrote 76 files (5.9 MB) to wp-tavern-astro
Next:
cd wp-tavern-astro
npm install
npm run dev
A converted post, src/content/posts/gutenberg-19-9-introduces-style-book-to-classic-themes.md:
---
title: "Gutenberg 19.9 Introduces Style Book to Classic Themes"
date: "2024-12-18T18:52:25Z"
updated: "2024-12-18T18:52:27Z"
slug: "gutenberg-19-9-introduces-style-book-to-classic-themes"
permalink: "/2024/12/18/gutenberg-19-9-introduces-style-book-to-classic-themes/"
categories: ["News"]
tags: ["gutenberg"]
excerpt: "The latest release of Gutenberg, version 19.9, brings a suite of powerful features, tools, and"
wordpressId: 182753
---
The latest release of [Gutenberg](https://make.wordpress.org/core/2024/12/18/whats-new-in-gutenberg-19-9-19-december/), version 19.9, brings a suite of powerful features, tools, and improvements for WordPress users. ...
### Style Book Comes to Classic Themesnpx needs only Node.js (16 or newer). The npm package ships a prebuilt binary for macOS, Linux and Windows (x64 and arm64).
npx wordpress-to-astro https://your-site.com # run once
npm install -g wordpress-to-astro # or keep it around
go install github.com/instapods/wordpress-to-astro@latest # or build it with Go 1.24+Binaries for every platform are also on the releases page. On macOS, a binary downloaded with a browser is quarantined; clear it with xattr -d com.apple.quarantine wordpress-to-astro (npx and go install don't need this).
wordpress-to-astro <site-url> [flags]
-o, --out <dir> Where to write the project (default: a folder named after the site)
-n, --max-posts <N> Convert only the newest N posts (default: all)
--dry-run Read a few posts and show what would convert; write nothing
--force Write into --out even if it is not empty
--timeout <dur> Give up after this long (default 30m)
--json Print the conversion report as JSON on stdout
-q, --quiet No progress output
-v, --version Print the version
Give it the address of the blog itself. For WordPress installed in a sub-directory (example.com/blog/) or a multisite sub-site, pass that full address: the converter reads the REST API the page advertises, not the one at the domain root.
Then, with Node.js 18.20 or newer (what Astro 5 needs):
cd your-site-astro
npm install
npm run dev # http://localhost:4321
npm run build # static site in dist/| From WordPress | In the Astro project |
|---|---|
| Published posts and pages | Markdown files in src/content/posts/ and src/content/pages/, with title, date, last update, slug, categories, tags, excerpt and featured image in the frontmatter |
| Images on your own domain | Downloaded to public/ at the same /wp-content/uploads/... path, and re-linked. Jetpack CDN (i0.wp.com) images are mapped back to your site |
| Permalinks | Every post and page is built at the exact path it has today |
| Category and tag archives | Rebuilt at their current paths, listing their posts |
| RSS and sitemap | /rss.xml and /sitemap-index.xml, generated on every build. The old /feed/ and sitemap addresses redirect to them |
| Site name, tagline, top-level pages | src/data/site.json, used for the header and menu |
Blocks that don't map cleanly to Markdown (tables, embeds, galleries, page-builder layouts) are kept as HTML inside the Markdown file. Nothing is silently dropped, and MIGRATION-NOTES.md in every project lists what came across and what did not, with counts for your site.
| Not converted | Why |
|---|---|
| Comments | They are personal data in your database, and a static site has nowhere to post new ones. Export them from WordPress (Tools, then Export) and add a comment service if you want them. The converter tells you how many you have. |
| Forms, search, shops, logins | They need PHP and a database at request time. The form markup is kept but will not submit; point it at a form service. |
| Shortcodes | The REST API returns content as WordPress renders it. Shortcodes from plugins that are no longer active come through as plain text like [gallery], and the converter lists every one it finds. |
| Page builders (Elementor, Divi, WPBakery) | Their layout lives in theme CSS and JavaScript the API does not expose. The content comes across as HTML and looks plainer until you restyle it. |
| Theme, menus, widgets | Not in the public API. The project ships a plain, readable layout you can restyle in src/layouts/Base.astro. |
| Drafts, private and password-protected posts | Only public content is read. Protected posts get a placeholder file so you know they exist. |
| Custom post types (products, portfolio items, events) | Only posts and pages are converted. The converter names each public custom type it finds and how many items it has. |
The rule: a post is built at exactly the URL it has on WordPress, so links and search rankings carry over. Only when that is impossible does a URL change, and then the old one gets a 301:
- Plain permalinks (
/?p=123,/?page_id=5): a static site can't route on a query string, so each post gets a clean path from its slug and the old link redirects. - Two items on one path: the second gets a
-<id>suffix. - Feeds and sitemaps:
/feed/,/wp-sitemap.xmland friends redirect to the new/rss.xmland/sitemap-index.xml.
Redirects are written twice: redirects.json, applied by the included dependency-free serve.mjs (npm start), and public/_redirects, which Netlify and Cloudflare Pages read. On any other host, copy the entries into its redirect settings.
your-site-astro/
README.md how to run, edit and deploy it
MIGRATION-NOTES.md what came across, what did not, notes for your site
astro.config.mjs site is set to your WordPress home URL
redirects.json old URL -> new URL
serve.mjs serves dist/ and applies redirects.json
public/
_redirects the same redirects for Netlify / Cloudflare Pages
wp-content/uploads/ your images, at their original paths
src/
content/posts/*.md
content/pages/*.md
data/site.json name, tagline, menu
data/terms.json categories and tags
layouts/Base.astro the look
pages/[...path].astro rebuilds every original URL
pages/rss.xml.js
Dependencies are astro 5, @astrojs/rss and @astrojs/sitemap. Nothing else.
Prefer not to use a terminal? The same converter runs at instapods.com/tools/wordpress-to-astro: paste your URL to see a preview of a converted post, then download the project as a zip.
import "github.com/instapods/wordpress-to-astro/wp2astro"
c := &wp2astro.Converter{} // or set Client, Limits, Progress
p, err := c.Convert(ctx, "https://example.com", wp2astro.Options{MaxPosts: 100})
// p.Files: the project; p.Report: what was found and convertedConverter.Preview reads a handful of requests and converts one sample post without downloading anything.
The default limits suit a run on your own machine (every post, 2 GB of images, 30 minutes). If you run the converter on a server for other people, set every field of Limits and PreviewLimits, and pass a Client that refuses private and loopback addresses: the library fetches whatever URL it is given.
Bug reports are most useful with the site URL and its WordPress version: see CONTRIBUTING.md. Conversions that come out wrong are the main thing we want to hear about.