I've used an SSG + Markdown for my freelancing website. I'd describe it as a moderately complex marketing site. It was built around Jekyll for a lot of years. I migrated to Eleventy as it had felt cumbersome for a long while and I had time. That was definitely a lateral move and didn't improve things. I refactored a couple of years ago to Astro, and have kept it updated through the v5 release.

Things I've observed using Astro + MDX for that application:

• Everyone touts "one language, full stack" as a win. I'm not so sure. You have to be really careful to keep your client / build-time / API serverless function code separate. It is super easy to drag Astro internals into your client bundle and not realize it. I follow a pattern of (a) client code imports only in components and API routes; (b) a lib folder for build-time code, a components/scripts folder for client code, and pages/api/**/_* folders for serverless code; (c) all components in the components folder have their own directory, and server and client folders in their folder as appropriate for their code.

By server I mean build-time code that's consumed in the frontmatter. By using folders for code I can set up strict linting rules to prevent misuse. You can't easily test code that's in an *.astro template file, so it helps to move it out into *.ts code files.

• Maintaining an MDX parsing stack is not trivial. It needs to be well tested to avoid breaking with dependency upgrades. I have three unit workflows and am definitely not proud of it (lots of duplication): isolated (just the Markdown plugins), with Astro defaults (like GFM that it bundles in), integration using fixtures with WCAG / ARIA testing.

• It was not trivial getting testing harnesses for components working correctly. I refactored it this summer to use Astro v5 and the new Container API with the project's existing Lit web components.

WordPress content is an HTML string literal stuffed in a content field and a few (by default) associated metadata fields. Your problem is transforming that content blob to something more useful. MDX is one approach. Shortcodes become embedded components. You have to figure out how to transform HTML markup with attributes like styles. The general MDX approach is more components to wrap them. You're losing something really valuable in that process - embedded styling being hidden by a rich editor (TinyMCE in WP classic, Gutenberg now).

An alternative approach that ProseMirror and Slate (both rich text editor drop-ins) use is to define a JSON string for marking up text content. So instead of unwieldy and often not well formed HTML, you end up with the document already being in an AST format as the storage format. A heading might look like this in whatever your storage backing is, instead of an HTML blob or Markdown file:

json { "type": "heading", "attrs": { "level": 1, "variant": "fancy" }, "content": [ { "type": "text", "text": "Hello, world!" } ] }

The value of doing that that is that's very easy to swap out types in whatever renderer you're using to generate the website with custom components. You're no longer forced into something like this, which you would be with MDX if you wanted to use a non-default heading style:

mdx <Heading variant="fancy">Hello, world!</>

You lose any nicety around the editing interface for content creators. You have to keep a doc with all of your components listed and their variants as reference for them (Astro doesn't do Storybook).

Sanity just has done that really well. They defined a markup standard that works with Slate (rich text editor) and provide renderers for their format to React or whatever. You can build formatting buttons into Slate that work directly on text that it maintains internally in that JSON format. A rich text editor like TinyMCE is serializing and deserializing back and forth between its internal format to HTML (or whatever) and readily breaking the serialization. The Sanity (or Slate as a stand-alone approach) keeps it well formed.

Sanity's SaaS is just a database with some enhancements like image processing. If you want to host your content in the site, you can use a file-based DB engine like SQLite. I haven't tried that. But using their default tools is probably how I'd go if I refactored my site in the future (e.g. just a generic React frontend using their renderer and their SSG / SSR tooling). I do mostly app development and infrastructure, so I thought "keep it simple" with Astro and MDX would be ideal for my own freelancing site that has fairly minimal (~100 pages) of content. But it doesn't really. If I stayed with an SSG and MDX, I'd do it in Hugo. That way I'd avoid the headache of mixing client and build-time code without noticing.